Alphabetic listing

This chapter explains how keywords (functions and commands) 
are specified and used, then lists them all alphabetically. Use this 
chapter if you know which keyword you need to use, but need to check 
how to use it. Each one is listed with the specification of its usage, 
then a description of what it does.

Note: the example programs in this chapter do not include 
full error handling code. This means that the programs have been kept 
short and easy to understand, but may fail if, for example, you enter 
the wrong type of value for a variable.

If you want to develop programs from these examples, 
it is recommended that you add some error handling code to them. An 
earlier chapter covers Error handling.



Typing commands, functions and arguments

Commands, functions and arguments may be typed in any 
combination of UPPER and lower case.

To put more than one statement on a line, separate 
them by a space followed by a colon  eg: "CLS :PRINT "hello" 
:GET"

Any commands may be strung together like this, and 
as many of them as you like  provided the total line length 
does not exceed 255 characters. The colon is optional before a REM 
statement.

Where one space is allowed, any number of spaces is 
allowed, eg:
"CLS     : PRINT  "Press Esc""

Functions may be used as arguments to other functions 
or commands  eg
"PRINT LEFT$(A$,3)" and "a=COS(ABS(x))" are OK.

How commands are specified

Commands are specified as "COMMAND argument(s)" 
where "argument(s)" follow the command after a space and 
are separated from each other by commas. The arguments may include:

Floating-point expression (eg "SIN(30)+2"), variable 
(eg "price" or "z") or literal value (eg "78.9")

Integer expression (eg "3*567"), variable (eg "price%", 
or "price&" if in range) or literal value (eg "-5676")

Long integer expression (eg "3*56799"), variable 
(eg "profit&") or literal value (eg "-5676869")

String expression (eg" b$+MID$(a$)"), variable 
(eg "price$") or literal value (eg ""word"")

Logical file name ("A", "B", "C" or "D")

Field name

For example, "AT X%,Y%" might be used like this: 
"AT 15,2"

How functions are specified

Functions are specified as "variable=FUNCTION(argument(s))" 
where "variable" may be "f%" or "f&" for a function returning 
an integer or long integer result, "f" for a function returning 
a floating-point result, or "f$" for a function returning a string 
result. The argument(s):

follow the command immediately

are enclosed in brackets ( ) 

are separated from each other in the brackets by a 
comma

may include variables, literal values or expressions 
of the appropriate kind  integer, long integer, floating-point 
or string, as described above.

Eg "f$=LEFT$(g$,x%)" might be used like this: 
"PRINT LEFT$(fname$,2)"

If you use the wrong type of number as an argument it 
will, where possible, be converted. For example, you can use an integer 
for a floating-point argument, or a long integer for an integer argument. 
If the conversion is not possible  for example, if you use 
a floating-point number for an integer argument and its value is outside 
the range of integers  an error will be produced and the program 
stopped.

Some functions, such as GET, have no arguments.

 

ABS

Usage:

a=ABS(x)

Returns the absolute value of a floating-point number  that 
is, without any "+"/"-" sign  for example "ABS(-10.099)" 
is "10.099"

If "x" is an integer, you won't get an error, but the result will 
be converted to floating-point  for example "ABS(-6)" is 
"6.0". Use IABS to return the absolute value as a long 
integer.

ACOS

Usage: 

a=ACOS(x)

Returns the arc cosine, or inverse cosine (COS^-1) of "x". 


"x" must be in the range -1 to +1. The number returned will be 
an angle in radians. To convert the angle to degrees, use the DEG 
function.

ADDR

Usage:

a%=ADDR(variable)

Returns the address at which "variable" is stored in memory. 

The values of different types of variables are stored in bytes starting 
at "ADDR(variable)". See PEEK for details.

See also UADD, USUB.

ADJUSTALLOC

Usage:

pcelln%=ADJUSTALLOC(pcell%,
		off%,am%)

Opens or closes a gap at "off%" within the allocated cell "pcell%", 
returning the new cell address or zero if out of memory. "off%" 
is 0 for the first byte in the cell. Opens a gap if the amount "am%" 
is positive, and closes it if negative.

ALERT

Usage  any of:

r%=ALERT(m1$,m2$,b1$,b2$,b3$)
r%=ALERT(m1$,m2$,b1$,b2$)
r%=ALERT(m1$,m2$,b1$)
r%=ALERT(m1$,m2$)
r%=ALERT(m1$)

Presents an alert  a simple dialog  with the 
messages and keys specified, and waits for a response. "m1$" is 
the message to be displayed on the first line, and "m2$" on the 
second line. If "m2$" is not supplied or if it is a null string, 
the second message line is left blank.

Up to three keys may be used. "b1$", "b2$" and "b3$" are 
the strings (usually words) to use over the keys. "b1$" appears 
over an "Esc" key, "b2$" over "Enter", and "b3$" over 
"Space". This means you can have "Esc", or "Esc" and "Enter", 
or "Esc", "Enter" and "Space" keys. If no key strings 
are supplied, the word "CONTINUE" is used above an "Esc" key.

The key number  1 for "Esc", 2 for "Enter" or 3 for 
"Space"  is returned.

ALLOC

Usage:

pcell%=ALLOC(size%)

Allocates a cell on the heap of the specified size, returning the 
pointer to the cell or zero if there is not enough memory.

APP

Usage:

APP name
...
ENDA

Begins definition of an OPA. "name" gives the name of the OPA.

See the Advanced Topics chapter for more details of OPAs.

APPEND

Usage:

APPEND

Adds a new record to the end of the current data file. The record 
which was current is unaffected. The new record, the last in the file, 
becomes the current record.

The record added is made from the current values of the field variables 
"A.field1$", "A.field2$", and so on, of the current data file. 
If a field has not been assigned a value, zero will be assigned to 
it if it is a numeric field, or a null string if it is a string field.

Example:

PROC add:
OPEN "address",A,f1$,f2$,f3$
PRINT "ADD NEW RECORD"
PRINT "Enter name:",
INPUT A.f1$
PRINT "Enter street:",
INPUT A.f2$
PRINT "Enter town:",
INPUT A.f3$
APPEND
CLOSE
ENDP

To overwrite the current record with new field values, use UPDATE.

APPENDSPRITE

Usage:

APPENDSPRITE time%,bit$(),
		dx%,dy%
"or"
APPENDSPRITE time%,	bit$()

Appends a single bitmap-set to the current sprite.

"time%" gives the duration in tenths of seconds for the bitmap-set 
to be displayed before going on to the next bitmap-set in the sequence.

"bit$()" contains the names of bitmap files in the set, or "" 
to specify no bitmap. The array must have at least 6 elements:
"bit$(1)" for setting black pixels
"bit$(2)" for clearing black pixels
"bit$(3)" for inverting black pixels
"bit$(4)" for setting grey pixels
"bit$(5)" for clearing grey pixels
"bit$(6)" for inverting grey pixels

All the bitmaps in a single bitmap-set must be the same size or `Argument' 
error (-2) is raised on attempting to draw the sprite. Bitmaps in 
different bitmap-sets may differ in size.

"dx%" and "dy%", if supplied, are the (x,y) offsets from the 
sprite position to the top-left of this bitmap-set, with positive 
for right and down. The default value of each is zero.

ASC

Usage:

a%=ASC(a$)

Returns the character code of the first character of "a$". 

See the character set in the back of the User Guide for the character 
codes. Alternatively, use "A%=%char" to find the code for 
"char"  eg "%X" for `X'.

If a$ is a null string ("") ASC returns the value 0.

Example "A%=ASC("hello")" returns 104, the code for "h".

ASIN

Usage:

a=ASIN(x)

Returns the arc sine, or inverse sine (SIN^-1) of "x". 


"x" must be in the range -1 to +1. The number returned will be 
an angle in radians. To convert the angle to degrees, use the DEG 
function.

AT 

Usage:

AT x%,y%

Positions the cursor at "x"% characters across the text window 
and "y"% rows down. "AT 1,1" always moves to the top left 
corner of the window. Initially, the window is the full size of the 
screen, but you can change its size and position with the SCREEN 
command.

A common use of AT is to display strings at particular positions 
in the text window. For example:
"AT 5,2 :PRINT "message"".

*) PRINT statements without an AT display 
at the left edge of the window on the line below the last PRINT 
statement (unless you use `","' or `";"') and strings displayed 
at the top of the window eventually scroll off as more strings are 
displayed at the bottom of the window. 

*) Displayed strings always overwrite anything that is on the 
screen  they do not cause things below them on the screen to 
scroll down.

Example:

PROC records:
LOCAL k%
OPEN "clients",A,name$,tel$
DO
 CLS
 AT 1,7
 PRINT "Press a key to"
 PRINT "step to next record"
 PRINT "or Q to quit"
 AT 2,3 :PRINT A.name$
 AT 2,4 :PRINT A.tel$
 NEXT
 IF EOF
  AT 1,6 :PRINT "EndOfFile"
  FIRST
 ENDIF
 k%=GET
UNTIL k%=%Q OR k%=%q
CLOSE
ENDP

ATAN

Usage:

a=ATAN(x)

Returns the arc tangent, or inverse tanget (TAN^-1) of "x". 


The number returned will be an angle in radians. To convert the angle 
to degrees, use the DEG function.

BACK

Usage:

BACK

Makes the previous record in the current data file the current record. 


If the current record is the first record in the file, then the current 
record does not change. 

BEEP 

Usage:

BEEP time%,pitch%

Sounds the buzzer. The beep lasts for "time%/32" seconds  
so for a beep a second long make "time%"=32, etc. The maximum 
is 3840 (2 minutes).

The pitch (frequency) of the beep is  "512/(pitch%+1)" KHz.

"BEEP 5,300" gives a comfortably pitched beep.

If you make "time%" negative, BEEP first checks whether 
the sound system is in use (perhaps by another OPL program), and returns 
if it is. Otherwise, BEEP waits until the sound system is free.

Example  a scale from middle C:

PROC scale:
LOCAL freq,n%
REM n% relative to middle A
n%=3 REM start at middle C
WHILE n%<16
 freq=440*2**(n%/12.0)
 REM middle A = freq 440Hz
 BEEP 8,512000/freq-1.0
 n%=n%+1
 IF n%=4 OR n%=6 OR n%=9 OR
              n%=11 OR n%=13
  n%=n%+1
 ENDIF
ENDWH
ENDP

(Note that the "IF" statement should all be on the same line).

Alternatively, sound the buzzer with this statement: "PRINT CHR$(7)". 
This beeps at a fixed pitch for a fixed length of time. 

BREAK

Usage:

BREAK

Makes a program performing a DO...UNTIL or WHILE...ENDWH 
loop exit the loop and immediately execute the line following the 
UNTIL or ENDWH statement.

Example:
    (picture)

DO
 ...
 ....
 IF a=b
  BREAK
 ENDIF
 ..
 ...
 .....
UNTIL a=b
x%=3
..

BUSY

Usage - one of:

BUSY str$,c%,delay%
BUSY str$,c%
BUSY str$
BUSY OFF

"BUSY str$" displays "str$" in the bottom left of the screen, 
until "BUSY OFF" is called. Use this to indicate `Busy' messages, 
usually when an OPL program is going to be unresponsive to keypresses 
for a while.

If "c%" is given, it controls the corner in which the message 
appears:

"c%"	corner
0	top left
1	bottom left (default)
2	top right
3	bottom right

"delay%" specifies a delay time (in half seconds) before the message 
should be shown. Use this to prevent `busy' messages from continually 
appearing very briefly on the screen.

Only one message can be shown at a time. The string to display can 
be up to 19 characters long.

CACHE

Usage  one of:

CACHE init%,max%
CACHE ON
CACHE OFF

CACHE creates a procedure cache of a specified initial number 
of bytes "init%" which may grow up to the maximum size "max%". 
You should usually TRAP this.

Once a cache has been created, "CACHE OFF" prevents further 
cacheing, although the cache is still searched when calling subsequent 
procedures. "CACHE ON" may then be used to re-enable cacheing.

CACHEHDR

Usage:

CACHEHDR addr(hdr%())

Read the current cache index header into array "hdr%()", which 
must have at least 11 integer elements.

See the `Advanced topics' chapter for more details.

CACHEREC

Usage:

CACHEREC addr(rec%()),off%

Read the cache index record at offset "off%" into array "rec%()", 
which must have at least 18 integer elements.

See the `Advanced topics' chapter for more details.

CACHETIDY

Usage:

CACHETIDY

Remove from the cache any procedures that have returned to their callers.

CALL

Usage:

e%=CALL(s%,bx%,cx%,dx%,si%,
		di%)

This function enables you to make operating system calls. To use it 
requires extensive knowledge of the Operating System and related 
programming techniques. The syntax of this command is included here 
for completeness.

The INT number itself is the least significant byte of "s%". The 
AH value (the subfunction number) is the most significant byte of 
"s%". The values of the other arguments are passed to the corresponding 
8086 registers. The value of the AX register is returned.

CHANGESPRITE

Usage:

CHANGESPRITE ix%,time%,
		bit$(),dx%,dy%
"or"
CHANGESPRITE ix%,time%,bit$()

Changes the bitmap-set specified by "ix%" (1 for the first bitmap-set) 
in the current sprite, using the supplied bitmap files, offsets and 
duration in the same way as for APPENDSPRITE.

CHR$

Usage:

a$=CHR$(x%)

Returns the character with character code "x%". 

You can use it to display characters not easily available from the 
keyboard  for example, the instruction "PRINT CHR$(174)" 
displays "®".

The full character set is in the User Guide.

CLOSE

Usage:

CLOSE

Closes the current file (that is, the one which has been OPENed 
and most recently USEd).

If you've used ERASE to remove some records, CLOSE recovers 
the memory used by the deleted records, provided it is held either 
in the internal memory or on a Ram SSD.

CLOSESPRITE

Usage:

CLOSESPRITE id%

Closes the sprite with ID "id%".

CLS

Usage:

CLS

Clears the contents of the text window.

The cursor then goes to the beginning of the top line. If you have 
used CURSOR OFF the cursor is still positioned there, but is 
not displayed.

CMD$

Usage:

c$=CMD$(x%)

Returns the command-line arguments passed when starting a program. 
Null strings may be returned. "x%" should be from 1 to 5. cmd$(2) 
to cmd$(5) are only for OPAs (OPL applications).

cmd$(1) returns the full path name used to start the running 
program.

cmd$(2) returns the full path name of the file to be used by 
an OPA application.

cmd$(3) returns ""C"" for "Create file" or ""O"" for 
"Open file". If the OPA is being run with a new filename, this 
will return ""C"". This happens the very first time the OPA 
is used, and whenever a new filename is used to run it. Otherwise, 
the OPA is being run with the name of an existing file, and 
"cmd$(3)" will return ""O"".

cmd$(4) returns the alias information, if any. In 
practice this has no relevance for OPAs.

cmd$(5) returns the application name, as declared with the 
APP keyword.

See the Advanced Topics chapter for more details of OPAs.

See also GETCMD$.

COMPRESS

Usage:

COMPRESS src$,dest$

Copies data file "src$" to another data file "dest$". If "dest$" 
already exists, the records in "src$" are appended to the end 
of "dest$".

Deleted records are not copied. This makes COMPRESS particularly 
useful when copying from a Flash SSD. (The space used by deleted records 
on a Ram SSD or in internal memory is automatically freed when you 
close the file.)

If you want "src$" to overwrite instead of append to "dest$", 
use:
"TRAP DELETE dest$"
before the COMPRESS statement.

You can use wildcards if you wish to copy more than one file at a 
time. But if the first name contains any wildcards, the second name 
must not include a filename, just the device and directory to which 
the files are to be copied under their original names.

Example: to copy all the data files on A: (in "\OPD", the default 
directory) to "B:\BCK\":

COMPRESS "A:*.ODB","B:\BCK\"

(Remember the final backslash on the directory name.)

See COPY for copying any type of file.

CONTINUE

Usage:

CONTINUE

Makes a program immediately go to the UNTIL... line of a DO...UNTIL 
loop or the WHILE... line of a WHILE...ENDWH loop  
ie to the test condition.

Example:
    (picture)

DO
 ...
 .....
 ....
 IF a<3.5
  CONTINUE
 ENDIF
 ..
 ....
 ...
UNTIL a=b
..

See also BREAK.

COPY

Usage:

COPY src$,dest$

Copies the file "src$", which may be of any type, to the file 
"dest$". Any existing file with the name "dest$" is deleted. 
You can copy across devices. 

Use the appropriate file extensions to indicate the type of file, 
and wildcards if you wish to copy more than one file at a time: 

*) If "src$" contains wildcards, "dest$" must not specify 
a filename, just the device and directory to which the files are to 
be copied under their original names. 

*) You must specify either an extension or .* on the 
first filename. The file type extensions are listed in the User Guide.

Example:
To copy all the OPL files from internal memory (in "\OPL") to 
"B:\ME\":

COPY "M:\OPL\*.OPL","B:\ME\"

(Remember the final backslash on the directory name.)

See COMPRESS for more control over copying data files. If you 
use COPY to copy a data file, deleted records are copied 
and you cannot append to another data file.

There are more details of full file specifications in the Advanced 
Topics chapter.

COS

Usage:

c=COS(x)

Returns the cosine of "x", where "x" is an angle in radians. 


To convert from degrees to radians, use the RAD function.

COUNT

Usage:

c%=COUNT

Returns the number of records in the current data file. 

This number will be 0 if the file is empty.

CREATE

Usage:

CREATE file$,log,f1,f2,...

Creates a data file called "file$".

*) The filename may be a full file specification of up to 128 
characters. Field names may be up to 8 letters/numbers.

*) The file may have up to 32 fields, as specified by "f1", 
"f2"... (if viewed in the Database application, field "f1" 
starts on the top line of the window, "f2" is below it, etc.)

*) "log" specifies the logical file name  "A", 
"B", "C" or "D". This is used as an abbreviation for the 
file name when you use other data file commands such as USE. 


Immediately after the CREATE statement, the file is open and 
can be accessed.

Example:

"CREATE "CLIENTS",B,NM$,PHON$

would create a data file in the internal memory with the name "CLIENTS" 
and the logical name "B".

CREATESPRITE

Usage:

id%=CREATESPRITE

Creates a sprite, returning the sprite ID.

CURSOR

Usage  one of the following:

CURSOR ON"
"CURSOR OFF
CURSOR id%,asc%,w%,h%
CURSOR id%,asc%,w%,h%,type%
CURSOR id%

CURSOR ON switches the text cursor on at the current cursor 
position. Initially, no cursor is displayed.

You can switch on a graphics cursor in a window by following CURSOR 
with the ID of the window. This replaces any text cursor. At 
the same time, you can also specify the cursor's shape, and its position 
relative to the baseline of text.

"asc%" is the ascent  the number of pixels (-128 
to 127) by which the top of the cursor should be above the baseline 
of the current font. "h%" and "w%" (both from 0 to 255) are 
the cursor's height and width.

If you do not specify them, the following default values are used:
"asc%"	=font ascent
"h%"	=font height
"w%"	=2

If "type%" is given, it can have these effects:
"1"	obloid
"2"	not flashing
"4"	grey

You can add these values together to combine effects  eg if 
"type%" is 6 a grey non-flashing cursor is drawn.

An error is raised if "id%" specifies a bitmap rather than a window.

CURSOR OFF switches off any cursor.

DATETOSECS

Usage:

s&=DATETOSECS(yr%,mo%,dy%,
		hr%,mn%,sc%)

Returns the number of seconds since 00:00 on 1 January 1970 at the 
date/time specified.

Raises an error for dates before 1 January 1970.

The value returned is an unsigned long integer. (Values up to 
+2,147,483,647, which is 03:14:07 on 19/1/2038, are returned as expected. 
Those from +2,147,483,648 upwards are returned as negative numbers, 
starting from -2,147,483,648 and increasing towards zero.)

See also SECSTODATE, HOUR, MINUTE, SECOND.

DATIM$

Usage:

d$=DATIM$

Returns the current date and time from the system clock as a string  
for example:
""Fri 16 Oct 1992 16:25:30""
The string returned always has this format  3 mixed-case characters 
for the day, then a space, then 2 digits for the day of the month, 
and so on.

DAY

Usage:

d%=DAY

Returns the current day of the month (1 to 31) from the system clock.

DAYNAME$

Usage:

d$=DAYNAME$(x%)

Converts "x%",a number from 1 to 7, to the day of the week, expressed 
as a three letter string.

Eg "d$=DAYNAME$(1)" returns "MON".

Example:

PROC Birthday:
 LOCAL d&,m&,y&,dWk%
 DO
  dINIT
  dTEXT "","Date of birth",2
dTEXT "","eg 23 12 1963",$202
  dLONG d&,"Day",1,31
  dLONG m&,"Month",1,12
  dLONG y&,"Year",1900,2155
  IF DIALOG=0 :BREAK :ENDIF
  dWk%=DOW(d&,m&,y&)
  CLS :PRINT DAYNAME$(dWk%),
  PRINT d&,m&,y&
  dINIT
  dTEXT "","Again?",$202
  dBUTTONS "No",%N,"Yes",%Y
 UNTIL DIALOG<>%y
ENDP 

See also DOW.

DAYS

Usage:

d&=DAYS(day%,month%,year%)

Returns the number of days since 01/01/1900. 

Use this to find out the number of days between two dates.

Example:

PROC deadline:
 LOCAL a%,b%,c%,deadlin&
 LOCAL today&,togo%
 PRINT "What day? (1-31)"
 INPUT a%
 PRINT "What month? (1-12)"
 INPUT b%
 PRINT "What year? (19??)"
 INPUT c%
 deadlin&=DAYS(a%,b%,1900+c%)
 today&=DAYS(DAY,MONTH,YEAR)
 togo%=deadlin&-today&
 PRINT togo%,"days to go"
 GET
ENDP

See also dDATE, SECSTODATE.

dBUTTONS

Usage  one of these:

dBUTTONS p1$,k1%,p2$,k2%,
	p3$,k3%
dBUTTONS p1$,k1%,p2$,k2%
dBUTTONS p1$,k1%

Defines exit keys to go at the bottom of a dialog.

From one to three exit keys may be defined. Each pair of "p$" 
and "k%" specifies an exit key; "p$" is the text to be displayed 
above it, while "k%" is the keycode of the key. DIALOG 
returns the keycode of the key pressed (in lower case for letters).

For alphabetic keys, use the "%" sign  "%A" means `the 
code of "A"', and so on. An appendix lists the codes for keys 
(such as Tab) which are not part of the character set. If you use 
the code for one of these keys, its name (eg `Tab', or `Enter') will 
be shown in the key.

If you use a negative value for a "k%" argument, that key is a 
`Cancel' key. The corresponding positive value is used for the key 
to display and the value for DIALOG to return, but if you do 
press this key to exit, the var variables used in the commands 
like dEDIT, dTIME etc. will not be set. 

The Esc key will always cancel a dialog box, with DIALOG returning 
0. If you want to show the Esc key as one of the exit keys, use -27 
as the "k%" argument (its keycode is 27) so that the var 
variables will not be set if Esc is pressed.

There can be only one dBUTTONS item per dialog, and it takes 
up three lines on the screen. dBUTTONS must be the last dialog 
command you use before DIALOG itself.

Some keypresses, such as those using the Control key, cannot be specified.

This example presents a simple query, returning `True' 
for Yes, or `False' for No.

PROC query:
 dINIT
 dTEXT "","FORGET CHANGES",2
 dTEXT "","Sure?",$202
 dBUTTONS "No",%N,"Yes",%Y
 RETURN DIALOG=%y
ENDP

dCHOICE

Usage:

dCHOICE var choice%,p$,list$

Defines a choice list to go in a dialog.

"p$" will be displayed on the left side of the line. "list$" 
should contain the possible choices, separated by commas  for 
example, ""Yes,No"". One of these will be displayed on the right 
side of the line, and " LEFT   RIGHT " can be used to move between 
the choices.

"choice%" must be a LOCAL or a GLOBAL variable. 
It specifies which choice should initially be shown  1 for 
the first choice, 2 for the second, and so on. When you finish using 
the dialog, "choice%" is given a value indicating which choice 
was selected  again, 1 for the first choice, and so on.

dDATE

Usage:

dDATE var lg&,p$,min&,max&

Defines an edit box for a date, to go in a dialog.

"p$" will be displayed on the left side of the line.

"lg&", which must be a LOCAL or a GLOBAL variable, 
specifies the date to be shown initially. Although it will appear 
on the screen like a normal date, for example "15/03/92", "lg&" 
must be specified as "days since 1/1/1900".

"min&" and "max&" give the minimum and maximum values which 
are to be allowed. Again, these are in days since 1/1/1900. An error 
is raised if "min&" is higher than "max&". 

When you finish using the dialog, the date you entered is returned 
in "lg&", in days since 1/1/1900.

The system setting determines whether years, months or days are displayed 
first.

See also DAYS, SECSTODATE.

dEDIT

Usage:

dEDIT var str$,p$,len%
"or"
dEDIT var str$,p$

Defines a string edit box, to go in a dialog.

"p$" will be displayed on the left side of the line.

"str$" is the string variable to edit. Its initial contents will 
appear in the dialog. The length used when "str$" was defined 
is the maximum length you can type in.

"len%", if supplied, gives the width of the edit box (allowing 
for widest possible character in the font). The string will scroll 
inside the edit box, if necessary. If "len%" is not supplied, 
the edit box is made wide enough for the maximum width "str$" 
could possibly be.

See also dTEXT.

DEFAULTWIN

Usage:

DEFAULTWIN mode%

Change the default window (ID=1) to enable or disable the use of grey. 
Initially grey cannot be used in that window.

"mode%=1" enables the use of grey.
"mode%=0" disables the use of grey.

A side-effect of DEFAULTWIN is to clear the default window.

Using grey does use more memory than using black only.

You are advised to call DEFAULTWIN once and for all near the 
start of your program if you need to use grey. If it fails with `Out 
of memory' error, the program can then exit cleanly without losing 
vital information.

See also gGREY and gCREATE.

DEG

Usage:

d=DEG(x)

Converts from radians to degrees. 

Returns "x", an angle in radians, as a number of degrees. The 
formula used is: "180*x/PI"

All the trigonometric functions (SIN,COS etc.) work in radians, 
not degrees. You can use DEG to convert an angle returned by 
a trigonometric function back to degrees:

Example:

PROC xarctan:
 LOCAL arg,angle
 PRINT "Enter argument:";
 INPUT arg
 PRINT "ARCTAN of",arg,"is"
 angle=ATAN(arg)
 PRINT angle,"radians"
 PRINT DEG(angle),"degrees"
 GET
ENDP

To convert from degrees to radians, use RAD. 

DELETE

Usage:

DELETE filename$

Deletes any type of file.

You can use wildcards  for example, to delete all the OPL files 
in B:\OPL
"DELETE "B:\OPL\*.OPL""

The file type extensions are listed in the User Guide.

See also RMDIR.

dFILE

Usage:

dFILE var str$,p$,f%

Defines a filename edit box, to go in a dialog. A `Disk' selector 
is automatically added on the line below.

"p$" will be displayed on the left side of the line.

"f%" controls the type of file editor, and the kind of input allowed. 
You can add together any of the following values:

 

value	meaning
1	use an edit box
2	allow directory names
4	directory names only
8	disallow existing files
16	query existing files
32	allow null string input
64	don't display extension
128	obey/allow wildcards

The first of the list is the most crucial. If you add 1 into "f%", 
you will see an file edit box, as when creating a new file. If you 
do not add 1, you will see the `matching file' selector, used when 
choosing an existing file.

If performing a `copy to' operation, you might use 1+2+16, to specify 
a file edit box, in which you can type the name of a directory 
to copy to, and which will produce a query if you type the name of 
an existing file.

If asking for the name of a directory to remove, you might use 4, 
to allow an existing directory name only.

`Query existing' is ignored if `disallow existing' is set. These two, 
as well as `allow null string input', only work with file edit boxes, 
not `matching file' selectors.

"str$" is the string variable to edit. Its initial contents always 
control the initial drive and directory used. For a file edit box, 
any filename part of "str$" is shown. For a `matching file' selector, 
you can use wildcards in the filename part (such as "*.tmp") to 
control which filenames are matched. To do this, you must add 128 
to "f%". 128 also allows wildcard specifications to be entered 
(returned in "str$"), for both `matching' and `new file' selectors.

If "str$" does not contain any drive or directory information, 
the path as set by SETPATH is used. If SETPATH has not 
been used, the "\OPD" directory on the default drive (usually 
"M:", `Internal') is used.

With a matching file selector (as opposed to an edit box) the 
value 8 restricts the selection to files which match the filename/extension 
in "str$". Matching file selectors can also use 64, in which case 
files with the same extension as that in "str$" are shown without 
this extension. (Many Series 3a file selectors are like this.)

You can always press Tab to produce the full file selector with a 
dFILE item.

"str$" must be declared to be at least 128 bytes long, or an error 
will be raised.

dFLOAT

Usage:

dFLOAT var fp,p$,min,max

Defines an edit box for a floating-point number, to go in a dialog.

"p$" will be displayed on the left side of the line.

"min" and "max" give the minimum and maximum values which 
are to be allowed. An error is raised if "min" is higher than 
"max".

"fp" must be a LOCAL or a GLOBAL variable. It specifies 
the value to be shown initially. When you finish using the dialog, 
the value you entered is returned in "fp".

DIALOG

Usage:

n%=DIALOG

Presents the dialog prepared by dINIT and commands such as 
dTEXT and dCHOICE. If you complete the dialog by pressing 
Enter, your settings are stored in the variables specified in dTEXT, 
dCHOICE etc., although you can prevent this with dBUTTONS.

If you used dBUTTONS when preparing the dialog, the keycode 
which ended the dialog is returned. Otherwise, DIALOG returns 
the line number of the item which was current when Enter was pressed. 
The top item (or the title line, if present), has line number 1.

If you cancel the dialog by pressing Esc, the variables are not changed, 
and 0 is returned.

DIAMINIT

Usage:

DIAMINIT pos%,str1$,str2$...

Initialises the DIAMOND list (discarding any existing list). "str1$", 
"str2$" etc. contain the text to be displayed in the status window 
for each item in the list.

"pos%" is the initial item on to which the DIAMOND indicator should 
be positioned, with "pos%=1" specifying the first item. (Any value 
greater than the number of strings specifies the final item.) If 
"pos%>=1" you must supply at least this many strings.

If "pos%" is not supplied or if "pos%=0", or if DIAMINIT 
is used on its own with no arguments, no bar is defined.

If "pos%=-1" the list is replaced by the icon instead in the large 
status window.

DIAMPOS

Usage:

DIAMPOS pos%

Positions the DIAMOND indicator on the DIAMOND list.

Positioning outside the range of the items wraps around in the appropriate 
way. "pos%=0" causes the DIAMOND symbol to disappear.

dINIT

Usage:

dINIT title$
"or"
dINIT

Prepares for definition of a dialog, cancelling any existing one. 
Use dTEXT, dCHOICE etc. to define each item in the dialog, 
then DIALOG to display the dialog.

If "title$" is supplied it will be displayed at the top of the 
dialog, centred and with a line across the dialog below it.

DIR$

Usage:

d$=DIR$(filespec$) "then"
d$=DIR$("")

Lists filenames, including subdirectory names, matching a file specification. 
You can include wildcards in the file specification. If "filespec$" 
is just a directory name, include the final backslash on the end  
for example, ""M:\TEMP\"" . Use the function like this:

*) "DIR$(filespec$)" returns the name of the first 
file matching the file specification. 

*) "DIR$("")" then returns the name of the second file 
in the directory.

*) "DIR$("")" again returns the third, and so on.

*) When there are no more matching files in the directory, 
"DIR$("")" returns a null string.

Example, listing all the ".DBF" files in "M:\DAT":

PROC dir:
 LOCAL d$(128)
 d$=DIR$("M:\DAT\*.DBF")
 WHILE d$<>""
  PRINT d$
  d$=DIR$("")
 ENDWH
 GET
ENDP

dLONG

Usage:

dLONG var lg&,p$,min&,max&

Defines an edit box for a long integer, to go in a dialog.

"p$" will be displayed on the left side of the line.

"min&" and "max&" give the minimum and maximum values which 
are to be allowed. An error is raised if "min&" is higher than 
"max&".

"lg&" must be a LOCAL or a GLOBAL variable. It specifies 
the value to be shown initially. When you finish using the dialog, 
the value you entered is returned in "lg&".

DO...UNTIL

Usage:

DO
 statement
 statement
 .
 .
 .
UNTIL condition

DO forces the set of statements which follow it to execute 
repeatedly until the "condition" specified by UNTIL is 
met.

This is the easiest way to repeat an operation a certain number of 
times.

*) Every DO must have its matching UNTIL to end 
the loop.

*) If you set a "condition" which is never met, the program 
will go round and round, locked in the loop forever. You can escape 
by pressing Psion-Esc, provided you haven't set ESCAPE OFF. 
If you have set ESCAPE OFF, you will have to return to the 
System screen, move to the program name under the RunOpl icon, and 
press Delete.

DOW

Usage:

d%=DOW(day%,month%,year%)

Returns the day of the week  from 1 (Monday) to 7 (Sunday)  
given the date. 

"day%" must be between 1 and 31, "month%" from 1 to 12 and 
"year%" from 1900 to 2155.

For example, "D%=DOW(4,7,1992)" returns 6, meaning Saturday.

dPOSITION

Usage:

dPOSITION x%,y%

Positions a dialog. Use dPOSITION at any time between dINIT 
and DIALOG.

dPOSITION uses two integer values. The first specifies the 
horizontal position, and the second, the vertical. "dPOSITION -1,-1" 
positions to the top left of the screen; "dPOSITION 1,1" to 
the bottom right;" dPOSITION 0,0" to the centre, the usual position 
for dialogs.

"dPOSITION 1,0", for example, positions to the right-hand edge 
of the screen, and centres the dialog half way up the screen.

DRAWSPRITE

Usage:

DRAWSPRITE x%,y%

Draws the current sprite in the current window with top-left at pixel 
position "x%,y%".

dTEXT

Usage:

dTEXT p$,body$,t%
"or"
dTEXT p$,body$

Defines a line of text to be displayed in a dialog.

"p$" will be displayed on the left side of the line, and "body$" 
on the right side. If you only want to display a single string, use 
a null string ("""") for "p$", and pass the desired string 
in "body$". It will then have the whole width of the dialog to 
itself. An error is raised if "body$" is a null string.

"body$" is normally displayed left aligned (although usually in 
the right column). You can override this by specifying "t%":

"t%"	effect
0	left align "body$"
1	right align "body$"
2	centre "body$"

In addition, you can add any or all of the following three values 
to "t%", for these effects:

"t%"	effect
$100	use bold text for "body$"
$200	draw a line below this
	item
$400	(allow this item to
	be selected)

Only one line can be drawn across a dialog. It will be below the last 
item which asks for it, whether the title from dINIT or a dTEXT 
item.

See also dEDIT.

dTIME

Usage:

dTIME var lg&,p$,t%,min&,max&

Defines an edit box for a time, to go in a dialog.

"p$" will be displayed on the left side of the line.

"lg&", which must be a LOCAL or a GLOBAL variable, 
specifies the time to be shown initially. Although it will appear 
on the screen like a normal time, for example "18:27", "lg&" 
must be specified as seconds after 00:00. A value of 60 means one 
minute past midnight; 3600 means one o'clock, and so on.

"min&" and "max&" give the minimum and maximum values which 
are to be allowed. Again, these are in seconds after 00:00. An error 
is raised if "min&" is higher than "max&". 

When you finish using the dialog, the time you entered is returned 
in "lg&", in seconds after 00:00.

"t%" specifies the type of display required, as follows:

"t%"	time display
0	absolute time no seconds
1	absolute time with seconds
2	duration no seconds
3	duration with seconds

For example, "03:45" represents an absolute time while 3 hours 
45 minutes represents a duration.

Absolute times are displayed in 24-hour or am/pm format according 
to the current system setting.

dXINPUT

Usage:

dXINPUT var str$,p$

Defines a secret string edit box, such as for a password, to go in 
a dialog.

"p$" will be displayed on the left side of the line.

"str$" is the string variable to take the string you type. Important: 
"str$" must be at least eight characters long.

Initially the dialog does not show any characters for the string; 
the initial contents of "str$" are ignored. A special symbol will 
be displayed for each character you type, to preserve the secrecy 
of the string.

EDIT

Usage:

EDIT a$

Displays a string variable which you can edit directly on the screen. 
All the usual editing keys are available  the arrow keys move 
along the line, Esc clears the line, and so on.

When you have finished editing, press Enter to confirm the changes. 
If you press Enter before you have made any changes, then the string 
will be unaltered.

If you use EDIT in conjunction with a PRINT 
statement, use a comma at the end of the PRINT statement, so 
that the string to be edited appears on the same line as the displayed 
string:

...
PRINT "Edit address:",
EDIT A.address$
UPDATE
....

TRAP EDIT 
If the Esc key is pressed while no text is on the input line, the 
`Escape key pressed' error (number -114) will be returned by ERR  
provided that the EDIT has been trapped. You can use this feature 
to enable someone to press the Esc key to escape from inputting a 
string.

See also INPUT, dEDIT.

ELSE(IF)/ENDA/ENDIF/ENDV/
ENDWH

See IF/APP/VECTOR/WHILE

ENTERSEND

Usage:

ret%=ENTERSEND(pobj%,m%,
		var p1,...)

This is the same as SEND except that, if the method leaves, 
the error code is returned to the caller. Otherwise the value returned 
is as returned by the method.

ENTERSEND0

Usage:

ret%=ENTERSEND0(pobj%,m%,
		var p1,...)

This is the same as ENTERSEND except that, if the method does 
not leave, zero is returned.

EOF 

Usage:

e%=EOF

Finds out whether you're at the end of a file yet. 

Returns -1 (true) if the end of the file has been reached, or 0 (false) 
if it hasn't. 

When reading records from a file, you should test whether there are 
still records left to read, otherwise you may get an error.

Example:

PROC eoftest:
OPEN "myfile",A,a$,b%
DO
 PRINT A.a$
 PRINT A.b%
 NEXT
 PAUSE -40
UNTIL  EOF
PRINT "The last record"
GET
RETURN
ENDP

 

ERASE

Usage:

ERASE

Erases the current record in the current file.

The next record is then current. If the erased record was the last 
record in a file, then following this command the current record will 
be null and EOF will return true.

ERR

Usage:

e%=ERR

Returns the number of the last error which occurred, or 0 if there 
has been no error.

Example:

..
PRINT "Enter age in years"
age::
TRAP INPUT age%
IF ERR=-1
 PRINT "Number please:"
 GOTO age
ENDIF
...

See also ERR$.

See the Error handling chapter for full details, including the list 
of error numbers and messages.

ERR$

Usage:

e$=ERR$(x%)

Returns the error message for the specified error code "x%". 

"ERR$(ERR)" gives the message for the last error which occurred. 
Example:

TRAP OPEN "B:\FILE",A,field1$
IF ERR
 PRINT ERR$(ERR)
 RETURN
ENDIF

See also ERR.

See the Error handling chapter for full details, including the list 
of error numbers and messages.

ESCAPE OFF

Usage:

ESCAPE OFF...ESCAPE ON

"ESCAPE OFF" stops Psion-Esc being used to break out of the 
program when it is running. "ESCAPE ON" enables this feature again.

"ESCAPE OFF" takes effect only in the procedure in which it occurs, 
and in any sub-procedures that are called. Psion-Esc is always enabled 
when a program begins running.

If your program enters a loop which has no logical exit, and "ESCAPE 
OFF" has been used, you will have to return to the System screen, 
move to the program name under the RunOpl icon, and press the Delete 
key.

EVAL

Usage:

d=EVAL(s$)

Evaluates the mathematical string expression "s$" and returns 
the floating-point result. "s$" may include any mathematical function 
or operator (eg. "sin(x)/(2**3)"). Note that floating-point arithmetic 
is always performed.

For example:

DO 
AT 10,5 :PRINT "Calc:",
TRAP INPUT n$
IF n$="" :CONTINUE :ENDIF
IF ERR=-114 :BREAK :ENDIF
CLS :AT 10,4
PRINT n$;"=";EVAL(n$)
UNTIL 0

See also VAL.

EXIST

Usage:

e%=EXIST(filename$) 

Checks to see that a file exists.

Returns -1 (`True') if the file exists and 0 (`False') if it doesn't.

Use this function when creating a file to check that 
a file of the same name does not already exist, or when opening a 
file to check that it has already been created:

IF NOT EXIST("CLIENTS")
 CREATE "CLIENTS",A,names$
ELSE
 OPEN "CLIENTS",A,names$
ENDIF
...

EXP

Usage:

e=EXP(x)

Returns ex  that is, the value of the arithmetic 
constant e (2.71828...) raised to the power of "x". 

EXT

Usage:

EXT name$

Gives the file extension of files used by an OPA.

This can only be used between APP and ENDA.

See the Advanced Topics chapter for more details of OPAs.

FIND

Usage:

f%=FIND(a$)

Searches the current data file for fields matching "a$". The search 
starts from the current record, so use NEXT to progress to 
subsequent records. FIND makes the next record containing "a$" 
the current record and returns the number of the record found. Capitals 
and lower-case letters match.

You can use wildcards:
"?" 	matches any single character
"*" 	matches any group of characters."

To find a record with a field containing  "Dr" and either "BROWN" 
or "BRAUN", use:
"F%=FIND("*DR*BR??N*")

"FIND("BROWN")" will find only those records with a field consisting 
solely of the string "BROWN".

You can only search string fields.

See also FINDFIELD.

FINDFIELD

Usage:

f%=FINDFIELD(a$,start%,no%,
		flags%)

FINDFIELD, like FIND, finds a string, makes the record 
with this string the current record, and returns the number of this 
record.

You may experience some problems in using FINDFIELD with some 
versions of OPL. To ensure that problems are avoided use the line:

POKEB(peekw($1c)+7),0

immediately before each call to FINDFIELD.

"a$" is the string to look for, as for FIND. "start%" 
is the number of the field to start looking in (1 for the first field), 
and "no%" is the number of fields to search in (starting from 
the field specified by the "start%"). If you want to search in 
all fields, use "start%=1" and for "no%" use the number of 
fields you used in the OPEN/CREATE command.

"flags%" adds together two values:

*) 0 for a case independent match, where capitals and 
lower-case letters match, or 1 for a case dependent match. This 
value should be multiplied by 16 (Hex $00 or $10).

*) 0 to search backwards from the current record, 1 to search 
forwards from the current record, 2 to search backwards from the end 
of the file, or 3 to search forwards from the start of the file.

FINDLIB

Usage:

ret%=FINDLIB(var cat%, name$)

Find DYL category "name$" (including ".DYL" extension) in 
the ROM. On success returns zero and writes the category handle to 
"cat%".

FIRST

Usage:

FIRST

Positions to the first record in the current data file.

FIX$

Usage:

f$=FIX$(x,y%,z%)

Returns a string representation of the number "x", to "y%" 
decimal places. The string will be up to "z%" characters long.

Example: "FIX$(123.456,2,7)" returns ""123.46"".

*) If "z%" is negative then the string is right-justified  
for example "FIX$(1,2,-6)" returns
""   1.00"" where there are two spaces to the left of the "1".

*) If "z%" is positive then no spaces are added  
for example "FIX$(1,2,6)" returns ""1.00"".

*) If the number "x" will not fit in the width specified 
by "z%", then the string will just be asterisks, for example "FIX$(256.99,2,4)" 
returns ""****"".

See also GEN$, NUM$, SCI$.

FLT

Usage:

f=FLT(x&)

Converts an integer expression (either integer or long integer) into 
a floating-point number. Example:

PROC gamma:(v)
 LOCAL c
 c=3E8
 RETURN 1/SQR(1-(v*v)/(c*c))
ENDP"

You could call this procedure like this: "gamma:(FLT(a%))" "if 
you wanted to pass it the value of an integer variable without having 
first to assign the integer value to a floating-point variable."

See also INT and INTF.

FONT

Usage:

FONT id%,style%

Sets the text window font and style.

See `The text and graphics windows' at the end of the `Graphics' chapter 
for more details.

FREEALLOC

Usage:

FREEALLOC pcell%

Frees a previously allocated cell at "pcell%".

gAT

Usage:

gAT x%,y%

Sets the current position using absolute co-ordinates. "gAT 0,0" 
moves to the top left of the current drawable.

See also gMOVE.

gBORDER

Usage:

gBORDER flags%,width%,height%
"or"
gBORDER flags%

Draws a one-pixel wide border around the edge of the current drawable. 
If "width%" and "height%" are supplied, a border shape of 
this size is drawn with the top left corner at the current position. 
If they are not supplied, the border is drawn around the whole of 
the current drawable.

"flags%" controls three attributes of the border  a shadow 
to the right and beneath, a one-pixel gap all around, and the type 
of corners used:

"flags%"	effect
1		single pixel shadow
2		gap for single pixel 
		shadow
3		double pixel shadow
4		gap for double pixel 
		shadow
$100		one-pixel gap all round
$200		more rounded corners

You can combine the values to control the three different effects. 
("1", "2", "3" and "4" are mutually exclusive  
you cannot use more than one of them.) For example, for rounded corners 
and a gap for a double pixel shadow, use "flags%=$204".

Set "flags%=0" for no shadow, no gap, and sharper corners.

For example, to de-emphasise a previously emphasised 
border, use gBORDER with the shadow turned off:

gBORDER 3 REM show border
GET
gBORDER 4 REM border off
...

See also gXBORDER.

gBOX

Usage:

gBOX width%,height%

Draws a box from the current position, "width%" to the right and 
"height%" down. The current position is unaffected.

gBUTTON

Usage:

gBUTTON text$,type%,
			w%,h%,st%

Draws a 3-D black and grey button (a key, not an application button) 
at the current position in a rectangle of the supplied width "w%" 
and height "h%", which fully encloses the button in all its states. 
"text$" specifies up to 64 characters to be drawn in the button 
in the current font and style. You must ensure that the text will 
fit in the button.

"type%=0" it draws a Series 3 style button; "type%=1" draws 
a Series 3a button.

The meaning of "state%" varies according to "type%":

*) For "type%=0", "state%=0" for a raised button and 
"state%=1" for a depressed (flat) button.

*) For "type%=1", "state%=0" for a raised button, "state%=1" 
for a semi-depressed (flat) button and "state%=2" for a fully-depressed 
(sunken) button. An error is raised if the current window has no grey 
plane.

gCLOCK

Usage - one of:

gCLOCK ON/OFF
gCLOCK ON,mode%
gCLOCK ON,mode%,offset%
gCLOCK ON,mode%,offset%,
		format$
gCLOCK ON,mode%,offset%,
		format$,font%
gCLOCK ON,mode%,offset%,
		format$,font%,style%

Displays or removes a clock showing the system time. The current position 
in the current window is used. Only one clock may be displayed in 
each window.

"mode%" controls the type of clock. Modes 1 to 5 are provided 
for Series 3 compatibility, and produce Series 3 clocks: small 
(digital), medium (system setting), medium (analog), medium (digital), 
and large (analog) respectively. Other values are:

"6"  black and grey medium, system setting
"7"  black and grey medium, analog
"8"  second type medium, digital
"9"  black and grey extra large 
"10" formatted digital (described below)

You can OR the value with any of these:
  "$10" shows the date in all except the extra large and formatted 
clocks
  "$20" shows seconds in small digital, large analog, black 
and grey medium analog and extra large clocks
  "$40" shows am/pm in small digital and black medium clocks 
only.
  "$80" specifies that a clock is to be drawn in the grey plane 
(only for clocks that do not contain both black and grey: ie. all 
except the black and grey, medium, analog clock and the extra large 
clock).

"format$", "font%" and "style%" are used only for formatted 
digital clocks as described below.

Do not use gSCROLL to scroll the region containing 
a clock. When the time is updated, the old position would be used. 
The whole window may, however, be moved using gSETWIN.

It is possible to draw clocks that include grey in windows 
that have no grey plane.

Digital clocks display in 24-hour or 12-hour mode according to the 
system-wide setting in Time. The `am/pm' flag ("$40") can be used 
with digital clocks in 12-hour mode, and with medium analog clocks.

"offset%" specifies an offset in minutes from the system time 
to the time displayed. This allows you to display a clock showing 
a time other than the system time.

If these arguments are not supplied, "mode%" is taken as 1, and 
"offset%" as 0.

For the formatted digital clock ("mode%=10"), you may optionally 
specify "font%" and "style%" with values as for gFONT 
and gSTYLE. The default font for gCLOCK is the system 
font (value $9a). The default style is normal (0).

For the formatted digital clock, a format string (up 
to 255 characters long) specifies how the clock is to be displayed. 
The format string contains a number of format specifiers in 
the form of a "%" followed by a letter. (Upper or lower case may 
be used.) For example, "%H" means "hours" and "%T" means "minutes"; 
"gCLOCK ON,10,0,"h:%H, m:%T"", at 11:05 pm, displays a running 
clock as "h:23, m:05".

To make each item as abbreviated as possible, you can use a "*" 
after the "%". For example, ""%*T"" at 11:05 pm abbreviates 
`05' to `5'. In the following list of specifiers, those which produce 
numbers will do so without any leading zero, if you use "%*" instead 
of "%". Other abbreviations are marked, appropriately, by "Abbrev":

 "%%" =a "%" character
 "%:", "%/" =time and date separators, as set in the Time 
application
 "%A" =`am' or `pm' text (Abbrev: 1st letter)
 "%D","%W","%M" =day/week/month number as two digits, 
01-31, 01-53 and 01-12
 "%E","%N" =day/month name (Abbrev: shorter form, 
eg 1st 3 characters in English)
 "%H","%I" =hour in 24-hour or 12-hour format, 00-23 and 
01-12
 "%S","%T" =seconds/minutes, 00-59
 "%X" =suffix string for day number, eg "st" in `1st', "nd" 
in `2nd'
 "%Y" =year as a four digit number (Abbrev: discards the 
century)
 "%1","%2","%3" =day,month,year as ordered in the Time 
application. Eg Europe is Day/month/year, so "%1=%D", "%2=%M", 
"%3=%Y". So to display a date in correct format use ""%1/%2/%3"". 
(Abbrev: see "%G"/"%P"/"%U".)
 "%4","%5" =day,month as ordered in the Time application.
 "%F","%O" =toggles days/months (displayed by "%1", 
"%2" and "%3") between numeric and name formats. On 9th March 
1993, with European date type, ""%1%F%1%F%1"" gives "09Tuesday09"
 "%G","%P", "%U" =toggles "%1", "%2" and "%3" 
between long form and abbreviation. On 9th March 1993, with European 
date type, ""%F%1%G%1%G%1"" gives "TuesdayTueTuesday"
 "%L" =toggles the suffix on the day number for "%1"/"%2"/"%3" 
(in numeric form only). On 9th March 1993, with European date type, 
""%G%1%L%1%L%1"" gives "99th9"
 "%6","%7" =hour and am/pm text according to the format 
selected in the Time application. With am-pm format, "%6=%I" and 
"%7=%A". With 24-hour format, "%6=%H" and "%7" gives no 
`am/pm' characters.

So the format string ""%1%/%2%/%3"" automatically generates a 
clock with day, month and year in the order as selected in the Time 
application. ""%4%/%5"" gives a clock with just day and month 
in selected order. Similarly, ""%6%:%T%:%S%7"" gives a clock with 
hour, minute and second automatically conforming to the system configuration.

Note that for those specifiers that toggle between two different 
options (eg. "%F"), the state of toggle is remembered only within 
one format string and not from one string to the next  ie the 
toggle state is restored to the default setting when displaying a 
new clock.

As a final example, assuming that the settings in the Time application 
are for `Day/month/year' date format, `am-pm' time format and `:' 
time separator and that the time is  11:30:05 pm on 9th March 1993, 
""%G%L%P%O%*E, %1 %2 
			%3 %6%:%T:%S%"" 
generates "Tue, 9th Mar 1993 11:30:05pm". With the same setup 
except for `Month/day/year' date format in `24-hour' mode, the same 
string generates "Tue, Mar 9th 1993 23:30:05".

gCLOSE

Usage:

gCLOSE id%

Closes the specified drawable that was previously opened by gCREATE, 
gCREATEBIT or gLOADBIT.

If the drawable closed was the current drawable, the default window 
(ID=1) becomes current.

An error is raised if you try to close the default window.

gCLS

Usage:

gCLS

Clears the whole of the current drawable and sets the current position 
to 0,0, its top left corner.

gCOPY

Usage:

gCOPY id%,x%,y%,w%,h%,mode%

Copies a rectangle of the specified size (width "w%", height "h%") 
from the point "x%,y%" in drawable "id%", to the current 
position in the current drawable.

As this command can copy both set and clear pixels, the same modes 
are available as when displaying text. Set "mode%" = 0 for set, 
1 for clear, 2 for invert or 3 for replace. 0, 1 and 2 act only on 
set pixels in the pattern; 3 copies the entire rectangle, with set 
and clear pixels.

The current position is not affected in either window.

gCOPY is affected by the setting of gGREY (in the current 
window) as follows: with "gGREY 0" it copies black to black; 
with "gGREY 1" it copies grey to grey, or black to grey if source 
is black only; with "gGREY 2" it copies grey to grey and black 
to black, or black to both if source is black only.

gCREATE

Usage:

id%=gCREATE(x%,y%,w%,h%,v%)
"or"
id%=gCREATE(x%,y%,w%,h%,v%,
		grey%)

Creates a window with specified position and size (width "w%", 
height "h%"), and makes it both current and foreground. Sets the 
current position to 0,0, its top left corner. If "v%" is 1, the 
window will immediately be visible; if 0, it will be invisible.

If "grey%" is not given or is 0, the window will not have a grey 
plane. If "grey%" is 1, it will have one.

Returns "id%" (2 to 8) which identifies this window for other 
keywords.

See also gCLOSE, gGREY, DEFAULTWIN.

gCREATEBIT

Usage:

id%=gCREATEBIT(w%,h%)

Creates a bitmap with the specified width and height, and makes it 
the current drawable. Sets the current position to 0,0, its top left 
corner.

Returns "id%" (2 to 8) which identifies this bitmap for other 
keywords.

See also gCLOSE.

gDRAWOBJECT

Usage:

gDRAWOBJECT type%,flags%,
		w%,h%

Draws the scaleable graphics object specified by "type%", scaled 
to fit in the rectangle with top left at the current graphics cursor 
position and with the specified width "w%" and height "h%".

The Series 3a has only one object type (set "type%=0")  
a `lozenge'. This is a 3-D rounded box lit from the top left, with 
a shadow at bottom right and a grey body. (For an example, see the 
text 'City' in the top left of the World application.)

For "type%=0", "flags%" specifies the corner roundness:
0 for normal roundness
1 for more rounded
2 for a single pixel removed from each corner.

An error is raised if the current window has no grey plane.

GEN$

Usage:

g$=gen$(x,y%)

Returns a string representation of the number "x". The string 
will be up to "y%" characters long.

Example "GEN$(123.456,7)" returns ""123.456"" and "GEN$(243,5)" 
returns ""243"

*) If "y%" is negative then the string is right-justified  
for example "GEN$(1,-6)" returns "
"     1"" where there are five spaces to the left of the 
"1".

*) If "y%" is positive then no spaces are added  
for example "GEN$(1,6)" returns ""1"".

*) If the number "x" will not fit in the width specified 
by "y%", then the string will just be asterisks, for example "GEN$(256.99,4)" 
returns ""****"".

See also FIX$, NUM$, SCI$.

GET

Usage:

g%=GET

Waits for a key to be pressed and returns the character code for that 
key. 

For example, if the `A' key is pressed with Caps Lock off, the integer 
returned is 97 ("a"), or 65 ("A") if `A' was pressed with 
the Shift key down. 

The character codes of special keys, such as `Pg Dn', are given 
in an appendix at the back of this manual.

You can use KMOD to check whether modifier keys (Shift, 
Control, Psion and Caps Lock) were used.

See the User Guide for the full character set.

See also KEY.

GET$

Usage:

g$=GET$

Waits until a key is pressed and then returns which key was pressed, 
as a string. 

For example, if the `A' key is pressed in lower case mode, the string 
returned is ""a"".

You can use KMOD to check whether any modifier keys 
(Shift, Control, Psion and Caps Lock) were used.

See also KEY$.

GETCMD$

Usage:

w$=GETCMD$

Returns new command-line arguments to an OPA, after a "change 
files" or "quit" event has occurred. The first character of the returned 
string is ""C"", ""O"" or ""X"". If it is ""C"" or 
""O"", the rest of the string is a filename.

The first character has the following meaning:

""C""  close down the current file, and create the specified 
new file.

""O""  close down the current file, and open the specified 
existing file.

""X""  close down the current file (if any) and quit the 
OPA.

You can only call GETCMD$ once for each system message.

See the Advanced Topics chapter for more details of OPAs.

See also CMD$.

GETEVENT

Usage:

GETEVENT var a%()

Waits for an event to occur. Returns with "a%()" specifying the 
event. The data returned in "a%()" depends on the type of event 
that occurred. If the event is a key-press, "(a%(1) AND $400)" 
is guaranteed to be zero. For other events "(a%(1) AND $400)" 
is guaranteed to be non-zero.

If a key has been pressed:
  "a%(1)"= keycode (as for GET)
  "a%(2) AND $00ff"= modifier (as for KMOD)
  "a%(2)/256"= auto-repeat count (ignored by GET)

If a program has moved to foreground:
  "a%(1)"= $401

If a program has moved to background:
  "a%(1)"= $402

If the machine has switched on:
  "a%(1)"= $403

If the Series 3a wants an OPA to change files or exit:
  "a%(1)"= $404

If the date changes:
  "a%(1)"= $405

Note: events are ignored while you are using keywords which 
wait for keypresses  GET, GET$, EDIT, 
INPUT, MENU and DIALOG. If you need to use these 
keywords in OPAs, use "LOCK ON / LOCK OFF" around them.

If you do use GETEVENT you should allow for other events to 
be specified in the future.

For a key-press event, the modifier is returned in "a%(2)" and 
is not returned by KMOD.

Note: If a non-key event such as `foreground' occurs while a keyboard 
keyword such as GET, INPUT, MENU or DIALOG 
is being used, the event is discarded. So GETEVENT must be 
used if non-key events are to be monitored. (OPAs can still handle 
the $404 event correctly  see the LOCK command for more 
details.)

The array (or string of integers) must be at least 6 integers 
long.

See also TESTEVENT, GETCMD$.

GETLIBH

Usage:

cat%=GETLIBH(num%)

Convert a category number "num%" to a handle. If "num%" is 
zero, gets the handle for OPL.DYL.

gFILL

Usage:

gFILL width%,height%,gMode%

Fills a rectangle of the specified size from the current position, 
according to the graphics mode specified.

The current position is unaffected.

gFONT

Usage:

gFONT fontId%

Sets the font for current drawable to "fontId%". The font may 
be one of the predefined fonts in the ROM or a user-defined font. 
See the `Graphics' chapter for more details of fonts.

User-defined fonts must first be loaded by gLOADFONT, which 
returns the "fontId%" needed for gFONT.

See also gLOADFONT, FONT.

gGMODE

Usage:

gGMODE mode%

Sets the effect of all subsequent drawing commands  gLINEBY, 
gBOX etc.  on the current drawable.

"mode%"		Pixels will be:
0		set
1		cleared
2		inverted

When you first use drawing commands on a drawable, they set pixels 
in the drawable. Use gGMODE to change this. For example, if 
you have drawn a black background, you can draw a white box outline 
inside it with either "gGMODE 1" or "gGMODE 2", followed 
by "gBOX".

gGREY

Usage:

gGREY mode%

Controls whether all subsequent graphics drawing and graphics text 
in the current window draw to the grey plane, the black plane 
or to both.

"mode%=0" for black plane only (default)
"mode%=1" for grey plane only
"mode%=2" for both planes

It is helpful to think of the black plane being in front of the grey 
plane, so a pixel set in both planes will appear black. See the `Graphics' 
chapter for details.

To enable the use of grey in the default window (ID=1) use "DEFAULTWIN 1" 
at the start of your program. If grey is required in other windows 
you must create the windows with a grey plane using gCREATE.

gGREY cannot be used with bitmaps which have only one plane.

See also DEFAULTWIN and gCREATE.

gHEIGHT

Usage:

height% = gHEIGHT

Returns the height of the current drawable.

gIDENTITY

Usage:

id%=gIDENTITY

Returns the ID of the current drawable.

The default window has ID=1.

gINFO

Usage:

gINFO var i%()

Gets general information about the current drawable and about the 
graphics cursor (whichever window it is in). The information is returned 
in the array "i%()" which must be at least 32 integers long.

The information is about the drawable in its current state, so eg 
the font information is for the current font in the current style.

The following information is returned:

"i%(1)	"	lowest character code
"i%(2)"		highest character code
"i%(3)"		height of font
"i%(4)"		descent of font
"i%(5)"		ascent of font
"i%(6)"		width of '0' character
"i%(7)"		maximum character width
"i%(8)"		flags for font (see below)
"i%(9-17)"	name of font
"i%(18)"	current graphics mode
		(gGMODE)
"i%(19)"	current text mode 
		(gTMODE)
"i%(20)"	current style (gSTYLE)
"i%(21)"	cursor state 
		(ON=1,OFF=0)
"i%(22)"	ID of window containing
		cursor (-1 for text cursor)
"i%(23)"	cursor width
"i%(24)"	cursor height
"i%(25)"	cursor ascent
"i%(26)"	cursor x position in 
		window
"i%(27)"	cursor y position in 
		window
"i%(28)"	1 if drawable is a bitmap
"i%(29)"	cursor effects
"i%(30)"	gGREY setting
"i%(31)"	reserved (window server 
		ID of drawable)
"i%(32)"	reserved

"i%(8)" specifies a combination of the following font characteristics:

Value:	Meaning:
1	font uses standard ASCII
	characters (32-126)
2	font uses Code Page 850
	characters (128-255)
4	font is bold
8	font is italic
16	font is serifed
32	font is monospaced
$8000	font is stored expanded
	for quick drawing

(See HEX$ for an explanation of hexadecimal numbers.)

Use "PEEK$(ADDR(i%(9)))" to read the name of the font as a string.

If the cursor is on ("i%(21)"=1), it is visible in the window 
identified by "i%(22)".

"i%(29)" has bit 0 set ("i%(29) AND 1") if the cursor 
is obloid, bit 1 set ("i%(29) AND 2") if not flashing, and 
bit 2 set ("i%(29) AND 4") if grey.

If the cursor is off ("i%(21)"=0), or is a text cursor ("i%(22)=-1"), 
"i%(23)" to "i%(27)" and "i%(29)" should be ignored.

gINVERT

Usage:

gINVERT width%,height%

Inverts the rectangle "width%" to the right and "height%" 
down from the cursor position, except for the four corner pixels.

GIPRINT

Usage:

GIPRINT str$,c%
"or"
GIPRINT str$

GIPRINT displays an information message for about two seconds, 
in the bottom right corner of the screen. For example, "GIPRINT "Not Found"" 
displays "Not Found". The string you specify can be up to 64 
characters. If a string is too long for the screen, it will be clipped.

If "c%" is given, it controls the corner in which the message 
appears:

"c%"	corner
0	top left
1	bottom left
2	top right
3	bottom right (default)

Only one message can be shown at a time. You can make the message 
go away  for example, if a key has been pressed  with 
"GIPRINT """.

gLINEBY

Usage:

gLINEBY dx%,dy%

Draws a line from the current position to a point "dx%" to the 
right and "dy%" down. Negative "dx%" and "dy%" mean left 
and up respectively.

For horizontal lines, the line includes the pixel with the lower x 
coordinate and excludes the pixel with the higher x coordinate. Similarly 
for vertical lines, the line includes the pixel with the lower y coordinate 
and excludes the pixel with the higher y coordinate. For oblique lines 
(where the x and y coordinates change), the line is drawn minus one 
or both end points.

The current position moves to the end of the line drawn.

"gLINEBY 0,0" sets the pixel at the current position.

See also gLINETO, gPOLY.

gLINETO

Usage:

gLINETO x%,y%

Draws a line from the current position to the point "x%,y%". The 
current position moves to "x%,y%".

For horizontal lines, the line includes the pixel with the lower x 
coordinate and excludes the pixel with the higher x coordinate. Similarly 
for vertical lines, the line includes the pixel with the lower y coordinate 
and excludes the pixel with the higher y coordinate. For oblique lines 
(where the x and y coordinates change), the line is drawn minus one 
or both end points.

To plot a single point, use gLINETO to the current position 
(or "gLINEBY 0,0").

See also gLINEBY, gPOLY.

gLOADBIT

Usage - one of:

id%=gLOADBIT(name$,write%,i%)
id%=gLOADBIT(name$,write%)
id%=gLOADBIT(name$)

Loads a bitmap from the named bitmap file and makes it the current 
drawable. Sets the current position to 0,0, its top left corner. If 
"name$" has no file extension ".PIC" is used. The bitmap is 
kept as a local copy in memory.

Returns "id%" (2 to 8) which identifies this bitmap for other 
keywords.

"write%"=0 sets read-only access. Attempts to write to the bitmap 
in memory will be ignored, but the bitmap can be used by other programs 
without using more memory. "write%"=1 allows you to write to and 
re-save the bitmap. This is the default case.

For bitmap files which contain more than one bitmap, "i%" specifies 
which one to load. For the first bitmap, use "i%"=0. This is also 
the default value. Bitmap files saved with gSAVEBIT have only one 
bitmap, and this argument is not needed for them.

See also gCLOSE.

gLOADFONT

Usage:

fontId%=gLOADFONT(name$)

Loads the user-defined font "name$". It returns a font ID; 
use this with gFONT to make the current drawable use this font. 
If "name$" does not contain a file extension, ".FON" is used. 


gFONT itself is very efficient, so you should normally load 
all required fonts at the start of a program.

Note that the built-in Series 3/Series 3a fonts are automatically 
available, and do not need loading.

See also gUNLOADFONT.

GLOBAL

Usage:

GLOBAL variables

Declares variables to be used in the current procedure (as does the 
LOCAL command) and (unlike LOCAL) in any procedures 
called by the current procedure, or procedures called by them.

The variables may be of 4 types, depending on the symbol they end 
with:

*) Variable names not ending with "$ % &" or "()" 
are floating-point variables, for example "price", "x"

*) Those ending with a "%" are integer variables, 
for example "x%", "sales92%"

*) Those ending with an "&"  are long integer variables, 
for example "x&", "sales92&".

*) Those ending with a "$" are string variables. 
String variable names must be followed by the maximum length of the 
string in brackets  for example "names$(12)", "a$(3)"

Array variables have a number immediately following them in 
brackets which specifies the number of elements in the array. Array 
variables may be of any type, for example: "x(6),y%(5),f$(5,12),z&(3)"

When declaring string arrays, you must give two numbers in the brackets. 
The first declares the number of elements, the second declares their 
maximum length. For example "surname$(5,8)" declares five elements, 
each up to 8 characters long.

Variable names may be any combination of up to 8 numbers and alphabetic 
letters. They must start with a letter. The length includes 
the "% &" or "$" sign, but not the "()" in string and 
array variables.

More than one GLOBAL or LOCAL statement may be used, 
but they must be on separate lines, immediately after the procedure 
name. 

See also LOCAL.

gMOVE

Usage:

gMOVE dx%,dy%

Moves the current position "dx%" to the right and "dy%" downwards, 
in the current drawable.

A negative "dx%" causes movement to the left; a negative "dy%" 
causes upward movement.

See also gAT.

gORDER

Usage:

gORDER id%,position%

Sets the window specified by "id%" to the selected foreground/background 
position, and redraws the screen. Position 1 is the foreground window, 
position 2 is next, and so on. Any position greater than the number 
of windows is interpreted as the end of the list.

On creation, a window is at position 1 in the list.

Raises an error if "id%" is a bitmap.

See also gRANK.

gORIGINX

Usage:

x%=gORIGINX

Returns the gap between the left side of the screen and the left side 
of the current window.

Raises an error if the current drawable is a bitmap.

gORIGINY

Usage:

y%=gORIGINY

Returns the gap between the top of the screen and the top of the current 
window.

Raises an error if the current drawable is a bitmap.

GOTO 

Usage:

GOTO label "or" GOTO label::
..
..
label::

Goes to the line following the "label::" and continues from there. 
The label 

*) Must be in the current procedure

*) Must start with a letter and end with a double colon, although 
the double colon is not necessary in the GOTO statement

*) May be up to 8 characters long excluding the colons.

gPATT

Usage:

gPATT id%,width%,height%,
		mode%

Fills a rectangle of the specified size from the current position 
with repetitions of the drawable "id%".

As with gCOPY, this command can copy both set and clear pixels, 
so the same modes are available as when displaying text. Set "mode%" 
= 0 for set, 1 for clear, 2 for invert or 3 for replace. 0, 1 and 
2 act only on set pixels in the pattern; 3 copies the entire rectangle, 
with set and clear pixels.

If you set "id%"=-1 a pre-defined grey pattern is used.

The current position is unaffected.

gPATT is affected by the setting of gGREY (in the current 
window) in the same way as gCOPY: with "gGREY 0" it 
copies black to black; with "gGREY 1" it copies grey to grey, 
or black to grey if source is black only; with "gGREY 2" it 
copies grey to grey and black to black, or black to both if source 
is black only.

gPEEKLINE

Usage:

gPEEKLINE id%,x%,y%,d%(),ln%

Reads a horizontal line from the black plane of the drawable "id%", 
length "ln%", starting at "x%,y%". The leftmost 16 pixels 
are read into "d%(1)", with the first pixel read into the least 
significant bit.

The array "d%()" must be long enough to hold the data. You can 
work out the number of integers required with "((ln%+15)/16)" 
(using whole-number division).

If you set "id%" to 0, this just reads from the whole screen, 
not from any particular window.

If you add $8000 to "id%", the grey plane (not the black plane) 
will be peeked. 

gPOLY

Usage:

gPOLY "a%()"

Draws a sequence of lines, as if by gLINEBY and gMOVE 
commands.

The array is set up as follows:

"a%(1)"	starting "x" position
"a%(2)"	starting "y" position
"a%(3)"	number of pairs of offsets
"a%(4)"	"dx1%"
"a%(5)"	"dy1%"
"a%(6)"	"dx2%"
"a%(7)"	"dy2%" etc.

Each pair of numbers  "dx1%,dy1%", for example  
specifies a line or a movement. To draw a line, "dy%" is the amount 
to move down, while "dx%" is the amount to move to the right multiplied 
by two.

To specify a movement (ie without drawing a line) work out the "dx%,dy%" 
as for a line, then add 1 to "dx%".

(For drawing/movement up or left, use negative numbers.)

gPOLY is quicker than combinations of gAT, gLINEBY 
and gMOVE.

Example, to draw three horizontal lines 50 pixels 
long at positions 20,10, 20,30 and 20,50:

a%(1)=20 :a%(2)=10 REM 20,10
a%(3)=5 REM 5 operations
REM draw right 50
a%(4)=50*2   :a%(5)=0
REM move down 20
a%(6)=0*2+1  :a%(7)=20
REM draw left 50
a%(8)=-50*2  :a%(9)=0
REM move down 20
a%(10)=0*2+1 :a%(11)=20
REM draw right 50
a%(12)=50*2  :a%(13)=0
gPOLY a%()

gPRINT

Usage:

gPRINT  list of expressions

Displays a list of expressions at the current position in the current 
drawable. All variable types are formatted as for PRINT.

Unlike PRINT, gPRINT does not end by moving to a new 
line. A comma between expressions is still displayed as a space, but 
a semi-colon has no effect. gPRINT without a list of expressions 
does nothing.

See also gPRINTB, gPRINTCLIP, gTWIDTH, gXPRINT, 
gTMODE.

gPRINTB

Usage  any of:

gPRINTB t$,w%,al%,tp%,bt%,m%
gPRINTB t$,w%,al%,tp%,bt%
gPRINTB t$,w%,al%,tp%
gPRINTB t$,w%,al%
gPRINTB t$,w%

Displays text "t$" in a cleared box of width "w%" pixels. 
The current position is used for the left side of the box and for 
the baseline of the text.

"al%" controls the alignment of the text in the box  1 
for right aligned, 2 for left aligned, or 3 for centred.

"tp%" and "bt%" are the clearances between the text and the 
top/bottom of the box. Together with the current font size, they control 
the height of the box. An error is raised if "tp%" plus the font 
ascent is greater than 255.

"m%" controls the margins. For left alignment, "m%" is an 
offset from the left of the box to the start of the text. For right 
alignment, "m%" is an offset from the right of the box to the 
end of the text. For centering, "m%" is an offset from the left 
or right of the box to the region in which to centre, with positive 
"m%" meaning left and negative meaning right.

If values are not supplied for some arguments, these defaults are 
used:

 

"al%"	left
"tp%"	0
"bt%"	0
"m%"	0

See also gPRINT, gPRINTCLIP, gTWIDTH, gXPRINT.

gPRINTCLIP

Usage:

w%=gPRINTCLIP(text$,width%)

Displays "text$" at the current position, displaying only as many 
characters as will fit inside "width%" pixels. Returns the number 
of characters displayed.

See also gPRINT, gPRINTB, gTWIDTH, gXPRINT, 
gTMODE.

gRANK

Usage:

rank%=gRANK

Returns the foreground/background position, from 1 to 8, of the current 
window.

Raises an error if the current drawable is a bitmap.

See also gORDER.

gSAVEBIT

Usage:

gSAVEBIT name$,width%,height%
"or"
gSAVEBIT name$

Saves the current drawable as the named bitmap file. If "width%" 
and "height%" are given, then only the rectangle of that size 
from the current position is copied. If "name$" has no file extension 
".PIC" is used.

Saving a window to file when it includes grey will save both planes 
to the file  black bitmap first followed by grey.

gSCROLL

Usage:

gSCROLL dx%,dy%,x%,y%,wd%,ht%
"or"
gSCROLL dx%,dy%

Scrolls pixels in the current drawable by offset "dx%,dy%". Positive 
"dx%" means to the right, and positive "dy%" means down. The 
drawable itself does not change its position.

If you specify a rectangle in the current drawable, at "x%,y%" 
and of size "wd%,ht%", only this rectangle is scrolled.

The areas "dx%" wide and "dy%" deep which are "left behind" 
by the scroll are cleared.

The current position is not affected.

gSETWIN

Usage:

gSETWIN x%,y%,width%,height%
"or"
gSETWIN x%,y%

Changes position and, optionally, the size of the current window.

An error is raised if the current drawable is a bitmap.

The current position is unaffected.

If you use this command on the default window, you must also 
use the SCREEN command to ensure that the area for PRINT 
commands to use is wholly contained within the default window.

gSTYLE

Usage:

gSTYLE style%

Sets the style of text displayed in subsequent gPRINT, gPRINTB 
and gPRINTCLIP commands on the current drawable.

"style%"	Text style:
0		normal
1		bold
2		underlined
4		inverse
8		double height
16		mono
32		italic

You can combine these styles by adding their values  for example, 
to set bold, underlined and double height, use "gSTYLE 11", 
as 11=1+2+8.

This command does not affect non-graphics commands, like PRINT.

gTMODE

Usage:

gTMODE mode%

Sets the way characters are displayed by subsequent gPRINT 
and gPRINTCLIP commands on the current drawable.

"mode%"		Pixels will be:
0		set
1		cleared
2		inverted
3		replaced

When you first use "graphics text" commands on a drawable, each dot 
in a letter causes a pixel to be set in the drawable. This is "mode%"=0.

When "mode%" is 1 or 2, graphics text commands work in a similar 
way, but the pixels are cleared or inverted. When "mode%" is 3, 
entire character boxes are drawn on the screen  pixels are 
set in the letter and cleared in the background box.

This command does not affect other text display commands.

gTWIDTH

Usage:

width%=gTWIDTH(text$)

Returns the width of "text$" in the current font and style.

See also gPRINT, gPRINTB, gPRINTCLIP, gXPRINT.

 gUNLOADFONT

Usage:

gUNLOADFONT fontId%

Unloads a user-defined font that was previously loaded using gLOADFONT. 
Raises an error if the font has not been loaded.

The built-in Series 3/Series 3a fonts are not held in memory and 
cannot be unloaded.

See also gLOADFONT.

gUPDATE

Usage  one of:

gUPDATE ON
gUPDATE OFF
gUPDATE

The Series 3a screen is usually updated whenever you display anything 
on it. "gUPDATE OFF" switches off this feature. The screen will 
then be updated as few times as possible (though note that some keywords 
will always cause an update.) You can still force an update by using 
the gUPDATE command on its own.

This can result in a considerable speed improvement in some cases. 
You might, for example, use "gUPDATE OFF", then a sequence of 
graphics commands, followed by "gUPDATE". You should certainly 
use gUPDATE OFF if you are about to write exclusively to 
bitmaps.

"gUPDATE ON" returns to normal screen updating.

gUPDATE affects anything that displays on the screen. If you 
are using a lot of PRINT commands, "gUPDATE OFF" may 
make a noticeable difference in speed.

Note that with gUPDATE OFF, the location of errors which 
occur while the procedure is running may be incorrectly reported. 
For this reason, gUPDATE OFF is best used in the final stages 
of program development, and even then you may have to remove it to 
locate some errors.

gUSE

Usage:

gUSE id%

Makes the drawable "id%" current. Graphics drawing commands will 
now go to this drawable. gUSE does not bring a drawable 
to the foreground (see gORDER).

gVISIBLE ON/OFF

Usage:

gVISIBLE ON/OFF

Makes the current window visible or invisible.

Raises an error if the current drawable is a bitmap.

gWIDTH

Usage:

width%=gWIDTH

Returns the width of the current drawable.

gX

Usage:

x%=gX

Returns the "x" current position (in from the left) in the current 
drawable.

gXBORDER

Usage:

gXBORDER type%,flags%,w%,h%
"or"
gXBORDER type%,flags%

Draws a border in the current drawable of a specified type, fitting 
inside a rectangle of the specified size or with the size of the current 
drawable if no size is specified.

"type%=0" for drawing the Series 3 type border; "flags%" 
are then as for gBORDER.

"type%=1" for drawing the Series 3a 3-D grey and black border. 
A shadow or a gap for a shadow is always assumed. "flags%=1,2,3,4" 
are as for gBORDER. When the shadow is enabled (1 or 3) only 
the grey and black parts of the border are drawn; you should pre-clear 
the background for the white parts. When the shadow is disabled (2 
or 4) the outer and inner border lines are drawn, but the areas covered 
by grey/black when the shadow is enabled are now cleared. (This allows 
a shadow to be turned off simply by calling gXBORDER again.)

The following values of "flags%" apply to all border types:
0 for normal corners
OR with $100 leaves 1 pixel gap around the border.
OR with $200 for more rounded corners
OR with $400 for losing a single pixel.

If both $400 and $200 are mistakenly supplied, $200 has priority.

An error is raised if the current window has no grey plane.

See also gBORDER.

gXPRINT

Usage:

gXPRINT string$,flags%

Displays "string$" at the current position, with precise highlighting 
or underlining. The current font and style are still used, even if 
the style itself is inverse or underlined. Text mode 3 (replace) is 
used  both set and cleared pixels in the text are drawn.

"flags%" has the following effect:

"flags%"	effect
0		normal, as with gPRINT
1		inverse
2		inverse, except corner 
		pixels
3		thin inverse
4		thin inverse, except 
		corner pixels
5		underlined
6		thin underlined

Where lines of text are separated by a single pixel, the thin 
options maintain the separation between lines.

gXPRINT does not support the display of a list of expressions 
of various types.

gY

Usage:

y%=gY

Returns the "y" current position (down from the top) in the current 
drawable.

HEX$

Usage:

h$=HEX$(x&)

Returns a string containing the hexadecimal (base 16) representation 
of integer or long integer "x&". 

For example "HEX$(255)" returns the string ""FF"". 

Notes 
To enter integer hexadecimal constants (16 bit) put a "$" in front 
of them. For example "$FF" is 255 in decimal. (Don't confuse this 
use of "$" with string variable names.)

To enter long integer hexadecimal constants (32 bit) put a "&" 
in front of them. For example "&FFFFF" is 1048575 in decimal.

Counting in hexadecimal is like this: "0 1 2 3 4 5 6 7 8 9 A B C 
D E F 10"...  "A" stands for decimal 10, "B" for decimal 
11, "C" for decimal 12 ... up to "F" for decimal 15. After 
"F" comes 10, which is equivalent to decimal 16. To understand 
numbers greater than hexadecimal 10, again compare hexadecimals with 
decimals. In these examples, 10^2 means 10x10, 10^3 means 
10x10x10 and so on.

253 in decimal is:
(2x10^2)+(5x10^1)+(3x10^0)
= (2x100)+(5x10)+(3x1)
= 200+50+3

By analogy, &253 in hexadecimal is:
(&2x16^2)+(&5x16^1)+(&3x16^0)
=(2x256)+(5x16)+(3x1)
=512+80+3 = 595 in decimal.

Similarly, &A6B in hexadecimal is:
(&Ax16^2)+(&6x16^1)+(&Bx16^0)
=(10x256)+(6x16)+(11x1)
=2560+96+11 = 2667 in decimal.

You may also find this table useful for converting between hex and 
decimal:

   "hex.      decimal		"
    &1   1      =16^0
   &10   16     =16^1
  &100   256    =16^2
 &1000   4096   =16^3

For example, &20F9 is (2x&1000)+(0x&100)+(15x&10)+9
which in decimal is: (2x4096)+(0x256)+(15x16)+9 = 8441.

All hexadecimal constants are integers ("$") or long integers 
("&"). So arithmetic operations involving hexadecimal numbers 
behave in the usual way. For example, "&3/&2" returns "1", 
"&3/2.0" returns "1.5", "3/$2" returns "1"."

HOUR

Usage:

h%=HOUR

Returns the number of the current hour from the system clock as an 
integer between 0 and 23. 

IABS

Usage:

i&=IABS(x&)

Returns the absolute value, ie without any sign, of the integer or 
long integer expression "x&". 

For example "IABS(-10)" is "10". 

See also ABS, which returns the absolute value as a floating-point 
value.

ICON

Usage:

ICON name$

Gives the name of the bitmap file to use as the icon for an OPA.

This can only be used between APP and ENDA.

See the Advanced Topics chapter for more details of OPAs.

IF...ENDIF 

Usage:

IF condition1
 ..
 ...
 .
ELSEIF condition2
 ...
 ....
ELSE
 ..
ENDIF

Does either 

*) the statements following the IF condition

or

*) the statements following one of the ELSEIF conditions 
(there may be as many ELSEIF statements as you like  
none at all if you want)

or

*) the statements following ELSE (or, if there is no 
ELSE, nothing at all). There may be either one ELSE 
statement or none.

After the ENDIF statement, the lines following ENDIF 
carry on as normal.

IF, ELSEIF, ELSE and ENDIF must be in that order.

Every IF must be matched with a closing ENDIF.

You can also have an IF...ENDIF structure within another, for 
example:

IF condition1
 ..
 ...
 .
ELSE
 ...
 IF condition2
 ....
 ENDIF
 ..
ENDIF

"condition" is an expression returning a logical value  
for example "a<b". If the expression returns logical true (non-zero) 
then the statements following are executed. If the expression returns 
logical false (zero) then those statements are ignored. For more details 
about logical expressions, see Appendix B.

INPUT

Usage:

INPUT variable
"or"
INPUT log.field

Waits for a value to be entered at the keyboard, and then assigns 
the value entered to a variable or data file field.

You can edit the value as you type it in. All the usual editing keys 
are available  the arrow keys move along the line, Esc clears 
the line and so on.

If inappropriate input is entered, for example a string when the input 
was to be assigned to an integer variable, a "?" is displayed 
and you can try again. However, if you used "TRAP INPUT", control 
passes on to the next line of the procedure, with the appropriate 
error condition being set and the value of the variable remaining 
unchanged.

INPUT is usually used in conjunction with a 
PRINT statement:

PROC exch:
LOCAL pds,rate
DO
 PRINT "Pounds Sterling?",
 INPUT pds
 PRINT "Rate (DM)?",
 INPUT rate
 PRINT "=",pds*rate,"DM"
 GET
UNTIL 0
ENDP

Note the commas at the end of the PRINT statements, used so 
that the cursor waiting for input appears on the same line as the 
messages.


TRAP INPUT 
If a bad value is entered (for example ""abc"" for "a%") in 
response to a TRAP INPUT, the "?" is not displayed, but 
the ERR function can be called to return the value of the error 
which has occurred. If the Esc key is pressed while no text is on 
the input line, the `Escape key pressed' error (number -114) will 
be returned by ERR (provided that the INPUT has been 
trapped). You can use this feature to enable someone to press the 
Esc key to escape from inputting a value.

See also EDIT. This works like INPUT, except that it 
displays a string to be edited and then assigned to a variable or 
field. It can only be used with strings.

INT

Usage:

i&=INT(x)

Returns the integer (in other words the whole number) part of the 
floating-point expression "x". The number is returned as a long 
integer.

Positive numbers are rounded down, and negative numbers are rounded 
up  for example "INT(-5.9)" returns "-5" and "INT(2.9)" 
returns "2". If you want to round a number to the nearest integer, 
add 0.5 to it (or subtract 0.5 if it is negative) before you use INT.

In the Calculator, you need to use INT to pass a number to 
a procedure which requires a long integer parameter. This is because 
the Calculator passes all numbers as floating-point by default.

See also INTF. 

INTF

Usage:

i=INTF(x)

Used in the same way as the INT function, but the value returned 
is a floating-point number. For example, "INTF(1234567890123.4)" 
returns "1234567890123.0"

You may also need this when an integer calculation may exceed integer 
range.

See also INT.

I/O functions

These functions are covered in detail in the Advanced Topics chapter.

r%=IOA(h%,f%,var status%,
		var a1,var a2)

The device driver opened with handle "h%" performs the 
asynchronous I/O function "f%" with two further arguments, "a1" 
and "a2". The argument "status%" is set by the device driver. 
An IOWAIT must be performed for each IOA.

r%=IOC(h%,f%,var status%,
		var a1,var a2)

Make an I/O request with guaranteed completion. This has 
the same form as IOA etc but it returns zero always.

r%=IOCANCEL(h%)

Cancels any outstanding asynchronous I/O request (IOC 
or IOA).

r%=IOCLOSE(h%)

Closes a file with the handle "h%".

r%=IOOPEN(var h%,name$,
		mode%)

Creates or opens a file called "name$". Defines "h%" 
for use by other I/O functions. "mode%" specifies how to open 
the file. For unique file creation, use
"IOOPEN(var h%,addr%,mode%)

r%=IOREAD(h%,addr%,maxLen%)

Reads from the file with the handle "h%". "address%" 
is the address of a buffer large enough to hold a maximum of "maxLen%" 
bytes. The value returned to "r%" is the actual number of bytes 
read or, if negative, is an error value.

r%=IOSEEK(h%,mode%,var off&)

Seeks to a position in a file that has been opened for random 
access. "mode%" specifies how the offset argument "off&" is 
to be used.

IOSIGNAL

Signals an I/O function's completion.

r%=IOW(h%,func%,var a1,
		var a2)

The device driver opened with handle "h%" performs the 
synchronous I/O function "func%" with the two further arguments.

IOWAIT

Waits for an asynchronous I/O function to signal completion.

IOWAITSTAT var stat%

Waits for an asynchronous function, called with IOA, 
to complete.

r%=IOWRITE(h%,addr%,length%)

Writes "length%" bytes in a buffer at "address%" 
to the file with the handle "h%".

IOYIELD

Ensures that any asynchronous handler set up with IOA 
is given a chance to run.

KEY

Usage:

k%=KEY

Returns the character code of the last key pressed, if there has been 
one since the last call to the keyboard. These functions count as 
calling to the keyboard: INPUT, EDIT, GET, GET$, KEY and KEY$.

If no key has been pressed, zero is returned. 

See Appendix D for a list of special key codes. You can use KMOD 
to check whether modifier keys (Shift, Control, Psion and 
Caps Lock) were used.

This command does not wait for a key to be pressed, unlike GET.

KEY$

Usage:

k$=KEY$

Returns the last key pressed as a string, if there has been a keypress 
since the last use of the keyboard by INPUT, EDIT, GET, GET$, 
KEY or KEY$.

If no key has been pressed, a null string ("") is returned. 

See Appendix D for a list of special key codes. You can use KMOD 
to check whether modifier keys (Shift, Control, Psion and 
Caps Lock) were used.

This command does not wait for a key to be pressed, unlike GET$.

KEYA

Usage:

err%=KEYA(var stat%,
		var key%(1))

This is an asynchronous keyboard read function.

See the Advanced Topics chapter for details.

Cancel with KEYC.

KEYC

Usage:

err%=KEYC(var stat%)

Cancels the previously called KEYA function with status "stat%".

See the Advanced Topics chapter for details.

KMOD

Usage:

k%=KMOD

Returns a code representing the state of the modifier keys (whether 
they were pressed or not) at the time of the last keyboard access, 
such as a KEY function. The modifiers have these codes:

			binary
2	Shift down	    10
4	Control down	   100
8	Psion down	  1000
16	Caps Lock on	 10000

If there was no modifier, the function returns 0. If a combination 
of modifiers was pressed, the sum of their codes is returned  
for example 20 is returned if Control (4) was held down and Caps Lock 
(16) was on.

Always use immediately after a KEY/KEY$/GET/GET$ statement.

The value returned by KMOD has one binary bit set for each 
modifier, as shown above. By using the logical operator AND 
on the value returned by KMOD you can check which of the bits 
are set, in order to see which modifier keys were held down. For more 
details on AND, see Appendix B.

Example:

PROC modifier:
LOCAL k%,mod%
PRINT "Press a key" :k%=GET
CLS :mod%=KMOD
PRINT "Key code",k%,"with"
IF mod%=0
 PRINT "no modifier"
ENDIF
IF mod% AND 2
 PRINT "Shift down"
ENDIF
IF mod% AND 4
 PRINT "Control down"
ENDIF
IF mod% AND 8
 PRINT "Psion down"
ENDIF
IF mod% AND 16
 PRINT "Caps Lock on"
ENDIF
ENDP

LAST

Usage:

LAST

Positions to the last record in a data file.

LCLOSE

Usage:

LCLOSE

Closes the device opened with LOPEN. (The device is also closed 
automatically when a program ends.)

LEFT$

Usage:

b$=LEFT$(a$,x%)

Returns the leftmost "x%" characters from the string "a$".

For example if "n$" has the value "Charles", then "b$=LEFT$(n$,3)" 
assigns "Cha" to "b$".

LEN

Usage:

a%=LEN(a$)

Returns the number of characters in "a$".

Eg if "a$" has the value
"34 Kopechnie Drive" then "LEN(a$)" returns "18". 


You might use this function to check that a data file string field 
is not empty before displaying:

IF LEN(A.client$)
 PRINT A.client$
ENDIF

LENALLOC

Usage:

len%=LENALLOC(pcell%)

Returns the length of the previously allocated cell at "pcell%".

LINKLIB

Usage:

LINKLIB cat%

Link any libraries that have been loaded using LOADLIB.

LN

Usage:

a=LN(x)

Returns the natural (base e) logarithm of "x". 

Use LOG to return the base 10 log of a number.

LOADLIB

Usage:

ret%=LOADLIB(var cat%,name$,
		link%)

Load and optionally link a DYL that is not in the ROM. If successful, 
this writes the category handle to "cat%" and returns zero. The 
DYL is shared in memory if already loaded by another process.

LOADM

Usage:

LOADM module$

Loads a translated OPL module so that procedures in that module can 
be called. Until a module is loaded with LOADM, calls to procedures 
in that module will give an error.

"module$" is a string containing the name of the module. Specify 
the full file name only where necessary.

Example "LOADM "MODUL2""

Up to 4 modules can be in memory at any one time; if you try to LOADM 
a fifth module, you get an error. Use UNLOADM to remove a module 
from memory so that you can load a different one.

By default, LOADM always uses the directory of the initial 
running program, or the one specified by a OPA application. 
It is not affected by the SETPATH command.

LOC

Usage:

a%=LOC(a$,b$) 

Returns an integer showing the position in "a$" where "b$" 
occurs, or zero if "b$" doesn't occur in "a$". The search 
matches upper and lower case.

Example: "LOC("STANDING","AND")" would return the value "3" 
because the substring "AND" starts at the third character of the 
string "STANDING".

LOCAL 

Usage:

LOCAL variables

Used to declare variables which can be referenced only in the current 
procedure. Other procedures may use the same variable names to create 
new variables. Use GLOBAL to declare variables common to all 
called procedures.

The variables may be of 4 types, depending on the symbol they end 
with:

*) Variable names not ending with "$ % &" or "()" 
are floating-point variables, for example "price", "x"

*) Those ending with a "%" are integer variables, 
for example "x%", "sales92%"

*) Those ending with an "&"  are long integer variables, 
for example "x&", "sales92&".

*) Those ending with a "$" are string variables. 
String variable names must be followed by the maximum length of the 
string in brackets, 
 for example "names$(12)", "a$(3)"

Array variables have a number immediately following them in 
brackets which specifies the number of elements in the array. Array 
variables may be of any type, for example: "x(6),y%(5),f$(5,12),z&(3)"

When declaring string arrays, you must give two numbers in the brackets. 
The first declares the number of elements, the second declares their 
maximum length. For example "surname$(5,8)" declares five elements, 
each up to 8 characters long.

Variable names may be any combination of up to 8 numbers and alphabetic 
letters. They must start with a letter. The length includes 
the "% &" or "$" sign, but not the "()" in string and 
array variables.

More than one GLOBAL or LOCAL statement may be used, 
but they must be on separate lines, immediately after the procedure 
name.

See also GLOBAL and Chapter 2. 

LOCK

Usage:

LOCK ON
"or"
LOCK OFF

Mark an OPA (OPL application) as locked or unlocked. When an OPA is 
locked with "LOCK ON", the System screen will not send it events 
to change files or quit. If, for example, you move onto the file list 
in the System screen and press Delete to try to stop that running 
OPA, a message will appear, indicating that the OPA cannot close down 
at that moment.

You should use "LOCK ON" if your OPA uses a command, such as 
EDIT or DIALOG, which accesses the keyboard. You might 
also use it when the OPA is about to go busy for a considerable length 
of time, or at any other point where a clean exit is not possible. 
Do not forget to use "LOCK OFF" as soon as possible afterwards.

`Foreground', `background' and `Machine on' events may still occur 
while the OPA is accessing the keyboard, and will be discarded.

An OPA is initially unlocked.

LOG

Usage:

a=LOG(x)

Returns the base 10 logarithm of "x".

Use LN to find the base e (natural) log.

LOPEN

Usage:

LOPEN device$

Opens the device to which LPRINTs are to be sent.

No LPRINTs can be sent until a device has been opened with 
LOPEN.

You can open any of these devices:

*) The parallel port, with "LOPEN "PAR:A""

*) The serial port, with "LOPEN "TTY:A""

*) A file on the Series 3a or an attached computer. LOPEN 
the file name, eg on a PC:

"LOPEN "REM::C:\BAK\MEMO.TXT""

or on an Apple Macintosh:

"LOPEN "REM::HD40:ME:MEMO5""

Any existing file of the name given will be overwritten 
when you print to it.

Only one device may be open at any one time. Use LCLOSE to 
close the device. (It also closes automatically when a program finishes 
running.)

See Appendix C.

LOWER$

Usage:

b$=LOWER$(a$)

Converts any upper case characters in the string "a$" to lower 
case and returns the completely lower case string.

Eg if a$=""CLARKE"", "LOWER$(a$)" returns the string "clarke"

Use UPPER$ to convert a string to upper case.

LPRINT

Usage:

LPRINT list of expressions

Prints a list of items, in the same way as PRINT, except that 
the data is sent to the device most recently opened with LOPEN.

The expressions may be quoted strings, variables, or the evaluated 
results of expressions. The punctuation of the LPRINT statement 
(commas, semi-colons and new lines) determines the layout of the printed 
text, in the same way as PRINT statements.

If no device has been opened with LOPEN you will get an error.

See PRINT for displaying to the screen.

See LOPEN for opening a device for LPRINT.

See Appendix C for an overview of printing from OPL.

MAX

Usage:

m=MAX(list)
"or"
m=MAX(array(),element)

Returns the greatest of a list of numeric items.

The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=MAX(arr(),3)" would return the value of the largest 
of elements "arr(1)", "arr(2)" and "arr(3)".

mCARD

Usage:

mCARD title$,n1$,k1%
"or"
mCARD title$,n1$,k1%,n2$,k2%
"etc."

Defines a menu. When you have defined all of the menus, use MENU 
to display them.

"title$" is the name of the menu. From one to eight items on the 
menu may be defined, each specified by two arguments. The first is 
the item name, and the second the keycode for a hot-key. This specifies 
a key which, when pressed together with the Psion key, will select 
the option. If the keycode is for an upper case key, the hot-key will 
use both the Shift and Psion keys.

The options can be divided into logical groups by displaying a grey 
line under the final option in 
a group. To do this, pass the negative value corresponding to the 
hot-key keycode for the final option in the group. For example, "-%A" 
specifies hot-key Shift-Psion-A and displays a grey line under the 
associated option in the menu.

MEAN

Usage:

m=MEAN(list)
"or"
m=MEAN(array(),element)

Returns the arithmetic mean (average) of a list of numeric items. 


The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=MEAN(arr(),3)" would return the average of elements 
"arr(1)", "arr(2)" and "arr(3)".

This example displays "15.0":"

a(1)=10
a(2)=15
a(3)=20
PRINT MEAN(a(),3)

MENU

Usage:

val%=MENU
"or"
val%=MENU (var init%)

Displays the menus defined by mINIT and mCARD, and waits 
for you to select an item. Returns the hot-key keycode of the item 
selected, as defined in mCARD, in lower case.

If you cancel the menu by pressing Esc, MENU returns 0.

If the name of a variable is passed is sets the initial menu and item 
to be highlighted. "init%" should be "256*(menu%)+item%"; 
for both "menu%" and "item%", 0 specifies the first, 1 the 
second and so on. If "init%" is 517 (=256*2+5), for example, this 
specifies the 6th item on the third menu.

If "init%" was passed, MENU writes back to "init%" 
the value for the item which was last highlighted on the menu. You 
can then use this value when calling the menu again. You only need 
to use this technique if you have more than one menu in your program.

MID$

Usage:

m$=MID$(a$,x%,y%)

Returns a string comprising "y%" characters of "a$", starting 
at the character at position "x%".

Eg if "name$="McConnell"" then "MID$(name$,3,3)" would return 
the string "Con".

MIN

Usage:

m=MIN(list)
"or"
m=MIN(array(),element)

Returns the smallest of a list of numeric items. 

The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=MIN(arr(),3)" would return the minimum of elements 
"arr(1)", "arr(2)" and "arr(3)".

mINIT

Usage:

mINIT

Prepares for definition of menus, cancelling any existing menus. Use 
mCARD to define each menu, then MENU to display them.

MINUTE

Usage:

m%=MINUTE

Returns the current minute number from the system clock (0 to 59). 


Eg at 8.54am "MINUTE" returns "54".

MKDIR

Usage:

MKDIR name$

Creates a new directory. For example, "MKDIR "M:\MINE\TEMP"" 
creates a "M:\MINE\TEMP" directory, also creating "M:\MINE" 
if it is not already there.

MONTH

Usage:

m%=MONTH

Returns the current month from the system clock as an integer between 
1 and 12. 

Eg on 12th March 1992 "m%=MONTH" returns "3" to "m%".

MONTH$

Usage:

m$=MONTH$(x%) 

Converts "x%", a number from 1 to 12, to the month name, expressed 
as a three-letter mixed case string.

Eg "MONTH$(1)" returns the string "Jan".

NEWOBJ

Usage:

pobj%=NEWOBJ(num%,clnum%)

Create a new object by category number "num%" belonging to the 
class "clnum%", returning the object handle on success or zero 
if out of memory.

NEWOBJH

Usage:

pobj%=NEWOBJH(cat%,clnum%)

Create a new object by category handle "cat%" belonging to the 
class "clnum%", returning the object handle on success or zero 
if out of memory.

NEXT

Usage:

NEXT

Positions to the next record in the current data file.

If NEXT is used after the end of a file has been reached, no 
error is reported but the current record is a null and the EOF 
function returns true. 

NUM$ 

Usage:

n$=NUM$(x,y%)

Returns a string representation of the integer part of the floating-point 
number "x", rounded to the nearest whole number. The string will 
be up to "y%" characters wide. 

*) If "y%" is negative then the string is right-justified  
for example "NUM$(1.9,-3)" returns "
"  2"" where there are two spaces to the left of the "2".

*) If "y%" is positive no spaces are added:  eg 
"NUM$(-3.7,3)" returns ""-4"".

*) If the string returned to "n$" will not fit in the width 
"y%", then the string will just be asterisks; for example "NUM$(256.99,2)" 
returns ""**"".

See also FIX$, GEN$, SCI$.

ODBINFO

Usage:

ODBINFO var info%() 

Provided for advanced use only, this keyword allows you to use OS 
and CALL to access data file interrupt functions not accessible 
with OPL keywords. See the `Advanced topics' chapter for more details.

OFF

Usage:

OFF
"or"
OFF x%

Switches the Series 3a off.

When you switch back on, the statement following the OFF command 
is executed, for example:
"OFF :PRINT "Hello again"" 

If you specify an integer, "x%", between 8 and 16383, the machine 
switches off for that number of seconds and then automatically turns 
back on and continues with the next line of the program (16383 is 
about 4 1/2  hours). However, during this time the machine may be 
switched on by an alarm, and of course you can turn it on with ON/Esc.

Warning: be careful how you use this command. If, due to a programming 
mistake, a program uses OFF in a loop, you may find it impossible 
to switch the Series 3a back on, and may have to reset the computer.

ONERR

Usage:"

ONERR label "or"
ONERR label::
..
..
ONERR OFF

"ONERR label::" establishes an error handler in a procedure. 
When an error is raised, the program jumps to the "label::" instead 
of the program stopping and an error message being displayed.

The label may be up to 8 characters long starting with a letter. It 
ends with a double colon ("::"), although you don't need to use 
this in the ONERR statement.

ONERR OFF disables the ONERR command, so that any errors 
occurring after the ONERR OFF statement no longer jump to the 
label. 

It is advisable to use the command ONERR OFF immediately after 
the "label::" which starts the error handling code.

See the Error handling chapter for full details.

OPEN 

Usage:

OPEN file$,log,f1,f2...

Opens an existing data file  "file$", giving it the logical file 
name "log", and giving the fields the names "f1," "f2"..

You need only specify those fields which you intend to update or append, 
though you cannot miss out a field.

The opened file is then referred to within the program by its logical 
name ("A", "B", "C" or "D").

Up to 4 files can be open at once. 

Example:

OPEN "clients",A,name$,addr$

See also CREATE, USE and OPENR.

OPENR

This command works exactly like OPEN except that the opened 
file is read-only  in other words, you cannot APPEND 
or UPDATE the records it contains.

This means that you can run two separate programs at the same time, 
both sharing the same file.

OS

Usage:

a%=OS(i%, addr1%)
"or"
a%=OS(i%, addr1%, addr2%)

Calls the Operating System interrupt "i%", reading the values 
of all returned 8086 registers and flags. The CALL function, although simpler to use, does not allow the AL register 
to be passed and no flags are returned, making it suitable only for 
certain interrupts.

The input registers are passed at the address "addr1%". The output 
registers are returned at the address "addr2%" if supplied, otherwise 
they are returned at "addr1%". Both addresses can be of an array, 
or of six consecutive integers.

Register values are stored sequentially as 6 integers and represent 
the register values in this order: AX, BX, CX, 
DX, SI and DI. The interrupt's function number, 
if required, is passed in AH.

The output array must be large enough to store the 6 integers returned 
in all cases, irrespective of the interrupt being called.

The value returned by OS is the flags register. The Carry flag, 
which is relevant in most cases, is in bit 0 of the returned value, 
so "(a% and 1)" will be `True' if Carry is set. Similarly, 
the Zero flag is in bit 6, the Sign flag in bit 7 and the Overflow 
flag in bit 10.

For example, to find "cos(pi/4)":

PROC add:
local a%,b%,c%,d%,si%,di%
local result,cosArg,flags% 
cosArg=pi/4
si%=addr(cosArg)
di%=addr(result)
ax%=$0100 REM AH=1
				 REM for cosine
flags%=os(140,addr(ax%))

The OS function requires extensive knowledge of the 
Operating System and related programming techniques.

See also CALL.

PARSE$

Usage:

p$=PARSE$(f$,rel$,var off%())

Returns a full file specification from the filename "f$", filling 
in any missing information from "rel$".

The offsets to the filename components in the returned string is returned 
in "off%()" which must be declared with at least 6 integers:

"off%(1)"	filing system offset 
		(1 always)
"off%(2)"	device offset
"off%(3)"	path offset
"off%(4)"	filename offset
"off%(5)"	file extension offset
"off%(6)"	flags for wildcards in
		returned string

The flag values in "offset%(6)" are:
0 : no wildcards
1 : wildcard in filename
2 : wildcard in file extension
3 : wildcard in both

If "rel$" is not itself a complete file specification, the current 
filing system, device and/or path are used as necessary to fill in 
the missing parts.

"f$" and "rel$" should be separate strings.

Example:

p$=PARSE("NEW",
   "LOC::M:\ODB\*.ODB",x%())

sets "p$" to "LOC::M:\ODB\NEW.ODB" and "x%()" to 
"(1,6,8,13,16,0)".

PATH

Usage:

PATH name$

Gives the directory to use for an OPA's files.

This can only be used between APP and ENDA.

See the Advanced Topics chapter for more details of OPAs.

PAUSE 

Usage:

PAUSE x%

Pauses the program for a certain time, depending on the value of "x%":

"x%"	result
0	waits for a key to be pressed.
+ve	pauses for "x%"  twentieths 
	of a second. 
-ve	pauses for "x%" twentieths 
	of a second or until a key 
	is pressed.

So "PAUSE 100" would make the program pause for  100/20  = 5 
seconds, and "PAUSE -100" would make the program pause for 5 seconds 
or until a key is pressed.

If "x%" is 0, a GET, GET$, KEY or KEY$ 
will return the key press which terminated the pause. If you are not 
interested in this keypress, but in the one which follows it, clear 
the buffer after the PAUSE with a single KEY function: 
"PAUSE 0 :KEY"

You should be especially careful about this if "x%" is negative, 
since then you cannot tell whether the pause was terminated by a keypress 
or by the time running out.

PEEK functions

The PEEK functions find the values stored in specific bytes.

Usage:

"p%=PEEKB(x%)" returns the integer value of the byte at address 
"x%"

"p%=PEEKW(x%)" returns the integer at address "x%"

"p&=PEEKL(x%)" returns the long integer value at address 
"x%"

"p=PEEKF(x%)" returns the floating-point value at address 
"x%"

"p$=PEEK$(x%)" returns the string at address "x%"

Usually you would find out the byte address with the ADDR function. 
For example, if "var%" has the value 7, "PEEKW(ADDR(var%))"  returns 
"7".

The different types are stored in different ways across bytes:

*) Integers are stored in two bytes. The first byte 
is the least significant byte, for example:
    (picture)

ADDR returns the address of the first (least significant) 
byte.

*) Long integers are stored in four bytes, the least 
significant first and the most significant last, for example:
    (picture)

ADDR returns the address of the first (least significant) 
byte.

*) Strings are stored with one character per byte, with 
a leading byte containing the string length, eg:
    (picture)

Each letter is stored as its character code  for 
example, "A" as 65. 

For example, if "var$="ABC"", "PEEK$(ADDR(var$))" 
will return the string "ABC". ADDR returns the address 
of the length byte.

*) Floating-point numbers are stored under IEEE 
format, across eight bytes. PEEKF automatically reads all eight 
bytes and returns the number as a floating-point. For example if "var=1.3" 
then "PEEKF(ADDR(var))" returns "1.3".

You can use ADDR to find the address of the first element in 
an array, for example "ADDR(x%())". You can also specify individual 
elements of the array, for example "ADDR(x%(2))".

See also the POKE commands and ADDR.

PI

Usage:

p=PI

Returns the value of Pi (3.14... ). 

POKE commands

The POKE commands store values in specific bytes.

Usage:

"POKEB x%,y%" stores the integer value "y%" (less than 256) 
in the single byte at address "x%"

"POKEW x%,y%" stores the integer "y%" across two consecutive 
bytes, with the least significant byte in the lower address, that 
is "x%"

"POKEL x%,y&" stores the long-integer "y&" in bytes starting 
at address "x%"

"POKEF x%,y" stores the floating-point value "y" in bytes 
starting at address "x%"

"POKE$ x%,y$" stores the string "y$" in bytes starting 
at address "x%"

Use ADDR to find out the address of your declared variables. 


Warning: Casual use of these commands can result in the loss 
of data in the Series 3a.

See PEEK for more details of how the different types are stored 
across bytes.

POS

Usage:

p%=POS

Returns the number of the current record in the current data file, 
from 1 (the first record) upwards.

A file can have up to 65534 records. However integers can only be 
in the range -32768 to +32767. Record numbers above 32767 are therefore 
returned like this:

record	value	returned by POS
32767		 32767
32768		-32768
32769		-32767
32770		-32766
.		.
.		.
65534		-2

To display record numbers, you can use this check:

IF POS<0
 PRINT 65536+POS
ELSE PRINT POS
ENDIF

POSITION 

Usage:

POSITION x%

Makes record number "x%" the current record in the current data 
file. 

If "x%" is greater than the number of records in the file then 
the EOF function will return true.

POSSPRITE

Usage:

POSSPRITE x%,y%

Set the position of the current sprite to pixel "x%,y%".

PRINT 

Usage:

PRINT list of expressions

Displays a list of expressions on the screen. The list can be punctuated 
in one of these ways:

*) If items to be displayed are separated by commas, there 
is a space between them when displayed.

*) If they are separated by semi-colons, there are no spaces.

*) Each PRINT statement starts a new line, unless the 
preceding PRINT ended with a semi-colon or comma.

*) There can be as many items as you like in this list. A single 
PRINT on its own just moves to the next line.

Examples:
On 1st January 1993, "
PRINT "TODAY is",
PRINT DAY;".";"MONTH "
would display "TODAY is 1.1"

PRINT 1             1
PRINT "Hello"       Hello
PRINT "Number",1    Number 1

See also LPRINT, gUPDATE, gPRINT, gPRINTB, 
gPRINTCLIP, gXPRINT.

RAD

"Usage:

r=RAD(x)

Converts "x" from degrees to radians.

All the trigonometric functions assume angles are specified in radians, 
but it may be easier for you to enter angles in degrees and then convert 
with RAD. 

Example:

PROC xcosine:
LOCAL angle
PRINT "Angle (degrees)?:";
INPUT angle
PRINT "COS of",angle,"is",
angle=RAD(angle)
PRINT COS(angle)
GET
ENDP

(The formula used is ^PI*x/180)

To convert from radians to degrees use DEG.

RAISE  

Usage:"

RAISE x%

Raises an error. 

The error raised is error number "x%". This may be one of the 
errors listed in the Error handling chapter, or a new error number 
defined by you.

The error is handled by the error processing mechanism currently in 
use  either OPL's own, which stops the program and displays 
an error message, or the ONERR handler if you have ONERR 
on.

For a full explanation, see the Error handling chapter.

RANDOMIZE 

Usage:"

RANDOMIZE x&

Gives a `seed' (start-value) for RND.

Successive calls of the RND function produce a sequence of 
random numbers. If you use RANDOMIZE to set the seed back to 
what it was at the beginning of the sequence, the same sequence will 
be repeated.

For example, you might want to use the same `random' values to test 
new versions of a procedure. To do this, precede the RND statement 
with the statement RANDOMIZE "value". Then to repeat the 
sequence, use RANDOMIZE "value" again.

Example:

PROC SEQ:
LOCAL g$(1)
WHILE 1
 PRINT "S: set seed to 1"
 PRINT "Q: quit"
 PRINT "other key: continue"
 g$=UPPER$(GET$)
 IF g$="Q"
  BREAK
 ELSEIF g$="S"
  PRINT "Setting seed to 1"
  RANDOMIZE 1
  PRINT "First random no:"
 ELSE
  PRINT "Next random no:"
 ENDIF
 PRINT RND
ENDWH
ENDP

REALLOC

Usage:

pcelln%=REALLOC(pcell%,
		size%)

Change the size of a previously allocated cell at "pcell%" to 
"size%", returning the new cell address or zero if there is not 
enough memory.

RECSIZE

Usage:"

r%=RECSIZE

Returns the number of bytes occupied by the current record. 

Use this function to check that a record may have data added to it 
without overstepping the 1022-character limit. 

Example:

PROC rectest:
LOCAL n$(20)
OPEN "name",A,name$
PRINT "Enter name:",
INPUT n$
IF RECSIZE<=(1022-LEN(n$))
 A.name$=n$
 APPEND
ELSE
 PRINT "Won't fit in record"
ENDIF
ENDP

REM

Usage:"

REM text

Precedes a remark you include to explain how a program works. All 
text after the REM up to the end of the line is ignored.

When you use REM at the end of a line you need only precede 
it with a space, not a space and a colon.

Examples:

INPUT a
b=a*.175 REM b=TAX

INPUT a
b=a*.175 :REM b=TAX

RENAME  

Usage:"

RENAME file1$,file2$

Renames "file1$" as "file2$". You can rename any type of file.

You cannot use wildcards.

You can rename across directories  "RENAME "\dat\x.dbf","\x.dbf"" 
is OK. If you do this, you can choose whether or not to change the 
name of the file.

Example:

PRINT "Old name:" :INPUT a$
PRINT "New name:" :INPUT b$
RENAME a$,b$

REPT$ 

Usage:"

r$=REPT$(a$,x%)

Returns a string comprising "x%" repetitions of "a$".

For example, if "a$="ex"", "r$=REPT$(a$,5)" returns "exexexexex".

RETURN 

Usage:"

RETURN" or "RETURN variable

Terminates the execution of a procedure and returns control to the 
point where that procedure was called (ENDP does this automatically).

"RETURN variable" does this as well, but also passes the value 
of "variable" back to the calling procedure. The variable may 
be of any type. You can return the value of any single array element  
for example "RETURN x%(3)". You can only return one variable.

"RETURN" on its own, and the default return through ENDP, 
causes the procedure to return the value 0 or a null string.

Example:
    (picture)

PROC price:
 LOCAL x
 PRINT "Enter price:",
 INPUT x
 x=tax:(x)
 PRINT x
 GET
ENDP

PROC tax:(price)
 RETURN price+17.5%
ENDP

RIGHT$

Usage:

r$=RIGHT$(a$,x%)

Returns the rightmost "x%" characters of "a$". 

Example:

PRINT "Enter name/ref",
INPUT c$
ref$=RIGHT$(c$,4)
name$=LEFT$(c$,LEN(c$)-4)

RMDIR

Usage:

RMDIR str$

Removes the directory given by "str$". You can only 
remove empty directories.

RND

Usage:"

r=RND

Returns a random floating-point number in the range 0 (inclusive) 
to 1 (exclusive).

To produce random numbers between 1 and "n"  eg between 
1 and 6 for a dice  use the following statement: "f%=1+INT(RND*n)"

RND produces a different number every time it is called within 
a program. A fixed sequence can be generated by using RANDOMIZE. 
You might begin by using RANDOMIZE with an argument generated 
from MINUTE and SECOND (or similar), to seed the sequence 
differently each time.

Example:

PROC rndvals:
LOCAL i%
PRINT "Random test values:"
DO
 PRINT RND
 i%=i%+1
 GET
UNTIL i%=10
ENDP

SCI$

Usage:

s$=SCI$(x,y%,z%)

Returns a string representation of "x" in scientific format, to 
"y%" decimal places and up to "z%" characters wide. Examples:

SCI$(123456,2,8)="1.23E+05"
SCI$(1,2,8)="1.00E+00"
SCI$(1234567,1,-8)=" 1.2E+06"

If the number does not fit in the width specified then the returned 
string contains asterisks.

If "z%" is negative then the string is right-justified.

See also FIX$, GEN$, NUM$.

SCREEN

Usage:

SCREEN width%,height%
"or"
SCREEN width%,height%,x%,y%

Changes the size of the window in which text is displayed. "x%,y%" 
specify the character position of the top left corner; if they are 
not given, the text window is centred in the screen.

An OPL program can initially display text to the whole screen.

SCREENINFO

Usage:

SCREENINFO var info%()

Gets information on the text screen (as used by PRINT etc.)

This keyword allows you to mix text and graphics. It is required because 
while the default window is the same size as the physical screen, 
the text screen is slightly smaller and is centred in the default 
window. The few pixels gaps around the text screen, referred to as 
the left and top margins, depend on the font in use.

On return, the array "info%()", which must have at least 10 elements, 
contains this information:

"info%(1)" left margin in pixels
"info%(2)" top margin in pixels
"info%(3)" text screen width in character units
"info%(4)" text screen height in character units
"info%(5)" reserved (window server id for default window)
"info%(6)" font id (FONT and gFONT)
"info%(7)" pixel width of text window character cell
"info%(8)" pixel height of text window line
"info%(9)", "info%(10)" reserved

Initially SCREENINFO returns the values for the initial text 
screen. Subsequently any keyword which changes the size of the text 
screen font, such as FONT, will change some of these values 
and SCREENINFO should therefore be called again.

See also FONT.

SECOND

Usage:

s%=SECOND

Returns the current time in seconds from the system clock (0 to 59). 


Eg at 6:00:33 "SECOND" returns "33".

SECSTODATE

Usage:

SECSTODATE s&,var yr%,
var mo%,var dy%,var hr%,
var mn%,var sc%,var yrday%

Sets the variables passed by reference to the date corresponding to 
"s&", the number of seconds since 00:00 on 1 January 1970. "yrday%" 
is set to the day in the year (1-366).

"s&" is an unsigned long integer. To use values greater 
than +2,147,483,647, subtract 4,294,967,296 from the value.

See also DATETOSECS, HOUR, MINUTE, SECOND, dDATE, DAYS.

SEND

Usage:

ret%=SEND(pobj%,m%,
		var p1,...)

Send a message to the object "pobj%" to call the method number 
"m%", passing between zero and three arguments ("p1"...) depending 
on the requirements of the method, and returning the value returned 
by the selected method. 

SETNAME

Usage:

SETNAME name$

Sets the name of the running OPA to "name$" and redraws any status 
window, using that name below the icon.

SETPATH

Usage:

SETPATH name$

Sets the current directory for file access  for example, "SETPATH "a:\docs"". 
LOADM continues to use the directory of the initial program, 
or the one specified by a OPA application, but all other file 
access will be to the new directory.

SIN

Usage:

s=SIN(angle)

Returns the sine of "angle", an angle expressed in radians.

To convert from degrees to radians, use the RAD function.

SPACE

Usage:

s&=SPACE

Returns the number of free bytes on the device on which the current 
(open) data file is held.

Example:

PROC stock:
OPEN "A:stock",A,a$,b%
WHILE 1
 PRINT "Item name:";
 INPUT A.a$
 PRINT "Number:";
 INPUT A.b%
 IF RECSIZE>SPACE
  PRINT "Disk full"
  CLOSE
  BREAK
 ELSE
  APPEND
 ENDIF
ENDWH
ENDP

SQR

Usage:

s=SQR(x)

Returns the square root of "x". 

STATUSWIN

Usage  one of:

STATUSWIN ON,type%
STATUSWIN ON
STATUSWIN OFF

Displays or removes a `permanent' status window.

If "type%=1" the small status window is shown. If "type%=2" 
the large status window is shown. STATUSWIN ON on its own 
displays an appropriate status window; on the Series 3a this will 
always be the large status window.

The permanent status window is behind all other OPL windows. 
In order to see it, you must use FONT (or both SCREEN 
and gSETWIN) to reduce the size of the text and graphics windows. 
You should ensure that your program does not create windows over the 
top of it.

STATWININFO

Usage:

t%=STATWININFO(type%, 
		var xy%())

Sets xy%(1),xy%(2), xy%(3) and xy%(4) to the top left x, top left 
y, width and height respectively of the specified type of status window. 
"type%=1" is the small status window; "type%=2" is the large 
status window; "type%=3" is the Series 3 compatibility mode 
status window; "type%=-1" is whichever status window is current.

STATWININFO returns "t%", the type of the current 
status window (with values as for "type%", or zero if there is 
no current status window).

STD

Usage:

s=STD(list)
"or"
s=STD(array(),element)

Returns the standard deviation of a list of numeric items. 

The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=STD(arr(),3)" would return the standard deviation 
of elements "arr(1)", "arr(2)" and "arr(3)".

This function gives the sample standard deviation, using the formula:

SQR(""(xi-x)^2/(n-1))" where 
"x" means" ""xi/n". To convert 
to population standard deviation, multiply the result by" SQR((n-1)/n).

STOP

Usage:

STOP

Ends the running program.

STYLE

Usage:

STYLE style%

Sets the text window character style. "style%" can be 2 for underlined, 
or 4 for inverse.

See `The text and graphics windows' at the end of the `Graphics' chapter 
for more details.

SUM

Usage:

s=SUM(list)
"or"
s=SUM(array(),element)

Returns the sum of a list of numeric items. 

The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=SUM(arr(),3)" would return the sum of elements 
"arr(1)", "arr(2)" and "arr(3)".

TAN

Usage:

t=TAN(angle)

Returns the tangent of "angle", an angle expressed in radians.

To convert from radians to degrees, use the DEG function.

TESTEVENT

Usage:

t%=TESTEVENT

Returns `True' if an event has occurred, otherwise returns `False'. 
The event is not read by TESTEVENT  it may be read with 
GETEVENT.

TRAP 

Usage:

TRAP command

TRAP is an error handling command. It may precede any of these 
commands:

Data file commands
APPEND, UPDATE
BACK, NEXT, LAST, FIRST, POSITION
USE, CREATE, OPEN, OPENR, CLOSE, DELETE

File commands
COPY, COMPRESS, ERASE, RENAME
LOPEN, LCLOSE
LOADM, UNLOADM

Directory commands
MKDIR, RMDIR

Data entry commands
EDIT, INPUT

Graphics commands
gSAVEBIT, gCLOSE, gUSE
gUNLOADFONT, gFONT, gPATT, gCOPY

For example, "TRAP FIRST". 

Any error resulting from the execution of the command will be trapped. 
Program execution will continue at the statement after the TRAP 
statement, but ERR will be set to the error code.

TRAP overrides any ONERR.

See the Error handling chapter for further details.

TYPE

Usage:

TYPE num%

Sets the type of an OPA, from 0 to 4, with "num%". On the Series 3a 
you should set "num%" from $1000 to $1004 to set type 0 to 4 respectively; 
the $1000 allows a 48x48 black/grey icon to be used.

This can only be used between APP and ENDA.

See the Advanced Topics chapter for more details of OPAs.

UADD

Usage:

i%=UADD(val1%, val2%)

Add "val1%" and "val2%", as if both were unsigned integers 
with values from 0 to 65535. Prevents integer overflow for pointer 
arithmetic  eg "UADD(ADDR(text$),1)" should be used instead 
of "ADDR(text$)+1".

One argument would normally be a pointer and the other an offset expression.

See also USUB.

UNLOADLIB

Usage:

ret%=UNLOADLIB(var cat%)

Unload a DYL from memory. If successful, returns zero.

UNLOADM

Usage:

UNLOADM module$

Removes from memory the module "module$" loaded with LOADM.

"module$" is a string containing the name of the translated module.

The procedures in an unloaded module cannot then be called by another 
procedure.

UNTIL

See DO.

UPDATE

Usage:

UPDATE

Deletes the current record in the current data file and saves the 
current field values as a new record at the end of the file.

This record, now the last in the file, remains the current record.

Example:

A.count=129
A.name$="Brown"
UPDATE

Use APPEND to save the current field values as a new record. 


UPPER$

Usage:

u$=UPPER$(a$)

Converts any lower case characters in "a$" to upper case, and 
returns the completely upper case string.

Example:

...
CLS :PRINT "Y to continue"
PRINT "or N to stop."
g$=UPPER$(GET$)
IF g$="Y"
 nextproc:
ELSEIF g$="N"
 RETURN
ENDIF
...

Use LOWER$ to convert to lower case.

USE

Usage:

USE logical name

Selects the data file with the logical name "A", "B", 
"C" or "D". The file must previously have been opened with 
OPEN, OPENR or CREATE and not yet be closed.

All the record handling commands (such as POSITION or UPDATE) 
then operate on this file.

USR

Usage:

u%=USR(pc%,ax%,bx%,cx%,dx%) 


Executes your machine code, returning an integer. The USR code 
(ie the assembler code you have written) must return with a far 
RET, otherwise the program will crash.

The values of of "ax%,bx%"... are passed to the AX, "BX"... 
8086 registers. The microprocessor then executes the machine code 
starting at "pc%". At the end of the routine, the value in the 
AX register is passed back to "u%".

WARNING: Casual use of this function can result in the loss 
of data in the Series 3a.

This example shows a simple operation, ending with a far RET:

PROC trivial:
LOCAL t%(2),u%,ax%
 t%(1)=$c032  REM xor al,al
 t%(2)=$cb    REM retf
 ax%=$1ab
u%=usr(addr(t%(1)),ax%,0,0,0)
 REM returns (ax% AND $FF00)
 PRINT u% REM 256 ($100)
 GET
ENDP

See also USR$, ADDR, PEEK, POKE.

USR$

Usage:

u$=USR$(pc%,ax%,bx%,cx%,dx%) 


Executes your machine code, returning a string. The USR$ code 
you have written must return with a far RET, otherwise the 
program will crash.

The values of of "ax%,bx%"... are passed to the ax, bx... 8086 
registers. The microprocessor then executes the machine code starting 
at "pc%". At the end of the routine, the value in the ax register 
must point to a length-byte preceded string. This string is then copied 
to "u$".

WARNING: Casual use of this function can result in the loss 
of data in the Series 3a.

See USR for an example. See also ADDR, PEEK, 
POKE.

USUB

Usage:

i%=USUB(val1%, val2%)

Subtract "val2%" from "val1%", as if both were unsigned integers 
with values from 0 to 65535. Prevents integer overflow for pointer 
arithmetic.

See also UADD.

VAL

Usage:

v=VAL(numeric string)

Returns the floating-point number corresponding to a numeric string.

The string must be a valid number  eg not ""5.6.7"" or 
""196f"". Expressions, such as ""45.6*3.1"", are not 
allowed. Scientific notation such as ""1.3E10"", is OK.

Eg "VAL("470.0")" returns "470"

See also EVAL.

VAR

Usage:

v=VAR(list)
"or"
v=VAR(array(),element)

Returns the variance of a list of numeric items. 

The list can be either:

*) A list of variables, values and expressions, separated by 
commas

or

*) The elements of a floating-point array. 

When operating on an array, the first argument must be the array name 
followed by "()". The second argument, separated from the first 
by a comma, is the number of array elements you wish to operate on  
for example" m=VAR(arr(),3)" would return the variance of elements 
"arr(1)", "arr(2)" and "arr(3)".

This function gives the sample variance, using the formula:

""(xi-x)^2/(n-1)" where 
"x" means ""xi/n". 
To convert to population variance, multiply the result by" 
(n-1)/n

VECTOR

Usage:

VECTOR I%
label1,label2,...
labelN
ENDV

"VECTOR I%" jumps to label number "i%" in the list  
if "i%" is 1 this will be the first label, and so on. The list 
is terminated by the ENDV statement. The list may spread over 
several lines, with a comma separating labels in any one line but 
no comma at the end of each line.

If "i%" is not in the range 1 to "N", where "N" is the 
number of labels, the program continues with the statement after the 
"ENDV" statement.

See also GOTO.

WEEK 

Usage:"

w%=WEEK(day%,month%,year%)

Returns the week number in which the specified day falls, as an integer 
between 1 and 53.

"day% "must be between 1 and 31, "month%" between 1 and 12, 
"year%" between 1900 and 2155.

Each week is taken to begin on the `Start of week' day, as specified 
in the Time application. When a year begins on a different day, it 
counts as week 1 if there are four or more days before the next week 
starts..

WHILE...ENDWH

Usage:

WHILE expression
 ..
 ...
 ..
 ....
ENDWH

Repeatedly performs the set of instructions between the WHILE 
and the ENDWH statement, so long as "expression "returns 
logical true  non-zero.

If "expression" is not true, the program jumps to the line after 
the ENDWH statement.

Every WHILE must be closed with a matching ENDWH.

See also DO...UNTIL and Chapter 3. 

YEAR

Usage:

y%=YEAR

Returns the current year as an integer between 1900 and 2155 from 
the system clock. 

For example, on 5th May 1992 "YEAR" returns "1992".